Skip to content

pynomina API Documentation

account_view

Created on 2024-10-12

@author: wf

AccountView

account display

Source code in nomina/account_view.py
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class AccountView:
    """
    account display
    """

    def __init__(self, solution: InputWebSolution, grid_row):
        """
        constructor
        """
        self.solution = solution
        self.lod_grid = None
        self.grid_row = grid_row
        self.setup_ui()

    def setup_ui(self):
        with self.grid_row:
            pass

    def style_grid(self, col_name: str, col_option: str, option_value: object):
        """
        style a part of the grid
        """
        for col_def in self.lod_grid.ag_grid.props["options"]["columnDefs"]:
            if col_def["field"] == col_name:
                col_def[col_option] = option_value
                pass

    def update(self, book: LedgerBook, account: LedgerAccount):
        """
        update my user interface with the given account
        """
        try:
            lod = []
            balance = 0.0
            row_num = 0
            for _tx_id, tx in book.transactions.items():
                for split in tx.splits:
                    if split.account_id == account.account_id:
                        if split.amount is not None:
                            row_num += 1
                            balance += split.amount
                            record = {
                                "#": row_num,
                                "Date": tx.isodate,
                                "Memo": split.memo,
                                "Amount": f"{split.amount:10.2f}",
                                "Ok": "⚫" if split.reconciled else "⚪",
                                "Balance": f"{balance:10.2f}",
                            }
                            lod.append(record)
            if self.lod_grid is None:
                key_col = "#"
                grid_config = GridConfig(
                    key_col=key_col,
                    editable=False,
                    multiselect=True,
                    with_buttons=False,
                    debug=False,
                )
                with self.grid_row:
                    self.lod_grid = ListOfDictsGrid(lod=lod, config=grid_config)
                    self.lod_grid.set_checkbox_selection(key_col)
                    # type: 'rightAligned'
                    self.style_grid("Amount", "type", "rightAligned")
                    self.style_grid("Balance", "type", "rightAligned")
                    self.style_grid(
                        "Amount",
                        "cellClassRules",
                        {"amount_negative": "x<0", "amount_positive": "x>=0"},
                    )
                    pass
                    # self.select_all_button.on("click", self.lod_grid.select_all_rows)
            else:
                with self.grid_row:
                    self.lod_grid.load_lod(lod)
                    self.lod_grid.update()
        except Exception as ex:
            self.solution.handle_exception(ex)
        pass

__init__(solution, grid_row)

constructor

Source code in nomina/account_view.py
19
20
21
22
23
24
25
26
def __init__(self, solution: InputWebSolution, grid_row):
    """
    constructor
    """
    self.solution = solution
    self.lod_grid = None
    self.grid_row = grid_row
    self.setup_ui()

style_grid(col_name, col_option, option_value)

style a part of the grid

Source code in nomina/account_view.py
32
33
34
35
36
37
38
39
def style_grid(self, col_name: str, col_option: str, option_value: object):
    """
    style a part of the grid
    """
    for col_def in self.lod_grid.ag_grid.props["options"]["columnDefs"]:
        if col_def["field"] == col_name:
            col_def[col_option] = option_value
            pass

update(book, account)

update my user interface with the given account

Source code in nomina/account_view.py
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def update(self, book: LedgerBook, account: LedgerAccount):
    """
    update my user interface with the given account
    """
    try:
        lod = []
        balance = 0.0
        row_num = 0
        for _tx_id, tx in book.transactions.items():
            for split in tx.splits:
                if split.account_id == account.account_id:
                    if split.amount is not None:
                        row_num += 1
                        balance += split.amount
                        record = {
                            "#": row_num,
                            "Date": tx.isodate,
                            "Memo": split.memo,
                            "Amount": f"{split.amount:10.2f}",
                            "Ok": "⚫" if split.reconciled else "⚪",
                            "Balance": f"{balance:10.2f}",
                        }
                        lod.append(record)
        if self.lod_grid is None:
            key_col = "#"
            grid_config = GridConfig(
                key_col=key_col,
                editable=False,
                multiselect=True,
                with_buttons=False,
                debug=False,
            )
            with self.grid_row:
                self.lod_grid = ListOfDictsGrid(lod=lod, config=grid_config)
                self.lod_grid.set_checkbox_selection(key_col)
                # type: 'rightAligned'
                self.style_grid("Amount", "type", "rightAligned")
                self.style_grid("Balance", "type", "rightAligned")
                self.style_grid(
                    "Amount",
                    "cellClassRules",
                    {"amount_negative": "x<0", "amount_positive": "x>=0"},
                )
                pass
                # self.select_all_button.on("click", self.lod_grid.select_all_rows)
        else:
            with self.grid_row:
                self.lod_grid.load_lod(lod)
                self.lod_grid.update()
    except Exception as ex:
        self.solution.handle_exception(ex)
    pass

bean_query

Created on 2024-11-02

@author: wf

BeanQueryHandler

Handles executing named parameterized queries using the BQLShell interface from beanquery.

Source code in nomina/bean_query.py
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
class BeanQueryHandler:
    """
    Handles executing named parameterized queries using the BQLShell interface from beanquery.
    """

    def __init__(
        self, beancount_file: str, format: str = "text", numberify: bool = False
    ):
        """
        Initialize the BeanQueryHandler with a Beancount file.

        Args:
            beancount_file (str): Path to the Beancount file.
            format (str): Output format (default: 'text').
            numberify (bool): Whether to remove currencies from the output (default: False).
        """
        self.shell = BQLShell(
            beancount_file,
            None,
            interactive=False,
            runinit=False,
            format=format,
            numberify=numberify,
        )

    def execute_query(
        self,
        query: str,
    ) -> list:
        """
        Execute a beanquery query

        Args:
            query (str): The query to execute.

        Returns:
            list: The query result rows as a list of dicts.
        """
        # Execute the query and return results directly
        cursor = self.shell.context.execute(query)
        rows = cursor.fetchall()
        # Get column names from cursor.description
        column_names = [col.name for col in cursor.description]

        # Construct list of dictionaries for each row
        lod = []
        for row in rows:
            row_dict = {}
            for i, value in enumerate(row):
                col = column_names[i]
                row_dict[col] = value
                if isinstance(value, Inventory):
                    position = value.get_only_position()
                    if position:
                        amount = position.units.number
                        currency = position.units.currency
                        row_dict[col] = amount
                        row_dict["currency"] = currency
            lod.append(row_dict)

        return lod

__init__(beancount_file, format='text', numberify=False)

Initialize the BeanQueryHandler with a Beancount file.

Parameters:

Name Type Description Default
beancount_file str

Path to the Beancount file.

required
format str

Output format (default: 'text').

'text'
numberify bool

Whether to remove currencies from the output (default: False).

False
Source code in nomina/bean_query.py
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def __init__(
    self, beancount_file: str, format: str = "text", numberify: bool = False
):
    """
    Initialize the BeanQueryHandler with a Beancount file.

    Args:
        beancount_file (str): Path to the Beancount file.
        format (str): Output format (default: 'text').
        numberify (bool): Whether to remove currencies from the output (default: False).
    """
    self.shell = BQLShell(
        beancount_file,
        None,
        interactive=False,
        runinit=False,
        format=format,
        numberify=numberify,
    )

execute_query(query)

Execute a beanquery query

Parameters:

Name Type Description Default
query str

The query to execute.

required

Returns:

Name Type Description
list list

The query result rows as a list of dicts.

Source code in nomina/bean_query.py
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def execute_query(
    self,
    query: str,
) -> list:
    """
    Execute a beanquery query

    Args:
        query (str): The query to execute.

    Returns:
        list: The query result rows as a list of dicts.
    """
    # Execute the query and return results directly
    cursor = self.shell.context.execute(query)
    rows = cursor.fetchall()
    # Get column names from cursor.description
    column_names = [col.name for col in cursor.description]

    # Construct list of dictionaries for each row
    lod = []
    for row in rows:
        row_dict = {}
        for i, value in enumerate(row):
            col = column_names[i]
            row_dict[col] = value
            if isinstance(value, Inventory):
                position = value.get_only_position()
                if position:
                    amount = position.units.number
                    currency = position.units.currency
                    row_dict[col] = amount
                    row_dict["currency"] = currency
        lod.append(row_dict)

    return lod

beancount_ledger

Created on 2024-10-07

@author: wf

BeancountToLedgerConverter

Bases: BaseToLedgerConverter

Convert Beancount format to Ledger Book

Source code in nomina/beancount_ledger.py
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
class BeancountToLedgerConverter(BaseToLedgerConverter):
    """
    Convert Beancount format to Ledger Book
    """

    def __init__(self, debug: bool = False):
        """
        Constructor for Beancount to Ledger Book conversion.

        Args:
            debug (bool): Whether to enable debug logging.
        """
        super().__init__(
            from_format_acronym="BEAN", debug=debug
        )  # Look up the formats using AccountingFileFormatDetector

        # Initialize instance variables
        self.beancount = None
        self.beancount_file = None
        self.ledger_book = None
        self.account_map = {}

    def load(self, input_path: str) -> Beancount:
        """

        load the beancount file

        Args:
            input_path (str): The path to the input file.
        """
        self.beancount_file = input_path
        beancount = Beancount()
        beancount.load_file(self.beancount_file)
        self.set_source(beancount)
        return self.beancount

    def set_source(self, source: LedgerBook):
        self.source = source
        self.beancount = source

    def convert_to_target(self) -> LedgerBook:
        """Convert the Beancount file to a Ledger Book."""
        self.ledger_book = LedgerBook()
        self.account_map: Dict[str, LedgerAccount] = {}

        for entry in self.beancount.entries:
            if isinstance(entry, data.Open):
                self.convert_account(entry)
            elif isinstance(entry, data.Transaction):
                self.convert_transaction(entry)

        return self.ledger_book

    def convert_account(self, entry: data.Open):
        """Create a Ledger account from a Beancount Open directive."""
        account_parts = entry.account.split(":")
        account_type = account_parts[0].upper()
        account_name = ":".join(account_parts[1:])

        ledger_account = LedgerAccount(
            account_id=entry.account,
            name=account_name,
            account_type=account_type,
            currency=entry.currencies[0] if entry.currencies else "EUR",
            description=entry.meta.get("description", ""),
        )
        self.ledger_book.add_account(ledger_account)
        self.account_map[entry.account] = ledger_account

    def convert_transaction(self, entry: data.Transaction):
        """Create a Ledger transaction from a Beancount Transaction."""
        splits = []
        for posting in entry.postings:
            amount = posting.units.number
            account_id = posting.account

            split = LedgerSplit(
                amount=float(amount),
                account_id=account_id,
                memo=posting.meta.get("memo", "") if posting.meta else "",
                reconciled=False,  # Beancount doesn't have a direct equivalent to Ledger's reconciled flag
                vat_code=posting.meta.get("vat_code") if posting.meta else None,
            )
            splits.append(split)

        ledger_transaction = LedgerTransaction(
            isodate=entry.date.isoformat(),
            description=entry.narration,
            splits=splits,
            payee=entry.payee,
            memo=entry.meta.get("memo", ""),
        )

        # date and description are not unique - the running number is, see issue #32
        transaction_id = (
            f"{ledger_transaction.isodate}:{len(self.ledger_book.transactions)}"
        )
        self.ledger_book.transactions[transaction_id] = ledger_transaction

__init__(debug=False)

Constructor for Beancount to Ledger Book conversion.

Parameters:

Name Type Description Default
debug bool

Whether to enable debug logging.

False
Source code in nomina/beancount_ledger.py
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def __init__(self, debug: bool = False):
    """
    Constructor for Beancount to Ledger Book conversion.

    Args:
        debug (bool): Whether to enable debug logging.
    """
    super().__init__(
        from_format_acronym="BEAN", debug=debug
    )  # Look up the formats using AccountingFileFormatDetector

    # Initialize instance variables
    self.beancount = None
    self.beancount_file = None
    self.ledger_book = None
    self.account_map = {}

convert_account(entry)

Create a Ledger account from a Beancount Open directive.

Source code in nomina/beancount_ledger.py
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def convert_account(self, entry: data.Open):
    """Create a Ledger account from a Beancount Open directive."""
    account_parts = entry.account.split(":")
    account_type = account_parts[0].upper()
    account_name = ":".join(account_parts[1:])

    ledger_account = LedgerAccount(
        account_id=entry.account,
        name=account_name,
        account_type=account_type,
        currency=entry.currencies[0] if entry.currencies else "EUR",
        description=entry.meta.get("description", ""),
    )
    self.ledger_book.add_account(ledger_account)
    self.account_map[entry.account] = ledger_account

convert_to_target()

Convert the Beancount file to a Ledger Book.

Source code in nomina/beancount_ledger.py
62
63
64
65
66
67
68
69
70
71
72
73
def convert_to_target(self) -> LedgerBook:
    """Convert the Beancount file to a Ledger Book."""
    self.ledger_book = LedgerBook()
    self.account_map: Dict[str, LedgerAccount] = {}

    for entry in self.beancount.entries:
        if isinstance(entry, data.Open):
            self.convert_account(entry)
        elif isinstance(entry, data.Transaction):
            self.convert_transaction(entry)

    return self.ledger_book

convert_transaction(entry)

Create a Ledger transaction from a Beancount Transaction.

Source code in nomina/beancount_ledger.py
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def convert_transaction(self, entry: data.Transaction):
    """Create a Ledger transaction from a Beancount Transaction."""
    splits = []
    for posting in entry.postings:
        amount = posting.units.number
        account_id = posting.account

        split = LedgerSplit(
            amount=float(amount),
            account_id=account_id,
            memo=posting.meta.get("memo", "") if posting.meta else "",
            reconciled=False,  # Beancount doesn't have a direct equivalent to Ledger's reconciled flag
            vat_code=posting.meta.get("vat_code") if posting.meta else None,
        )
        splits.append(split)

    ledger_transaction = LedgerTransaction(
        isodate=entry.date.isoformat(),
        description=entry.narration,
        splits=splits,
        payee=entry.payee,
        memo=entry.meta.get("memo", ""),
    )

    # date and description are not unique - the running number is, see issue #32
    transaction_id = (
        f"{ledger_transaction.isodate}:{len(self.ledger_book.transactions)}"
    )
    self.ledger_book.transactions[transaction_id] = ledger_transaction

load(input_path)

load the beancount file

Parameters:

Name Type Description Default
input_path str

The path to the input file.

required
Source code in nomina/beancount_ledger.py
44
45
46
47
48
49
50
51
52
53
54
55
56
def load(self, input_path: str) -> Beancount:
    """

    load the beancount file

    Args:
        input_path (str): The path to the input file.
    """
    self.beancount_file = input_path
    beancount = Beancount()
    beancount.load_file(self.beancount_file)
    self.set_source(beancount)
    return self.beancount

LedgerToBeancountConverter

Bases: BaseFromLedgerConverter

converter for Ledger Book to Beancount

Source code in nomina/beancount_ledger.py
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
class LedgerToBeancountConverter(BaseFromLedgerConverter):
    """
    converter for Ledger Book to Beancount
    """

    def __init__(self, debug: bool = False):
        """
        Constructor for Ledger Book to Beancount conversion.

        Args:
            debug (bool): Whether to enable debug logging.
        """
        super().__init__(to_format_acronym="BEAN", debug=debug)

        # Initialize instance variables
        self.lbook = None
        self.lbook_stats = None
        self.start_date = None
        self.beancount = None

    def load(self, input_path: str) -> LedgerBook:
        """
        load the Ledger Book

        Returns:
            LedgerBook: the ledger book
        """
        lbook = LedgerBook.load_from_yaml_file(input_path)  # # @UndefinedVariable
        self.set_source(lbook)
        return lbook

    def set_source(self, source: LedgerBook):
        self.source = source
        self.lbook = source

    def convert_to_target(self) -> Beancount:
        """
        Convert the ledger book to a Beancount object.
        Args:
            lbook (LedgerBook): The ledger book to convert.

        Returns:
            Beancount: The converted Beancount object.
        """
        self.lbook = self.source
        self.lbook_stats = self.lbook.get_stats()
        self.start_date = self.lbook.get_stats().start_date or DateUtils.iso_date(
            datetime.now()
        )
        self.beancount = Beancount()

        for account in self.lbook.accounts.values():
            self.beancount.add_entry(self.convert_account(account))

        for transaction in self.lbook.transactions.values():
            self.beancount.add_entry(self.convert_transaction(transaction))

        self.target = self.beancount
        return self.beancount

    def to_text(self):
        beancount = self.target
        preamble = Preamble(
            start_date=self.start_date,
            end_date=self.lbook_stats.end_date or "Unknown",
            title=self.lbook.name or "Converted Ledger",
            currency=self.lbook_stats.main_currency(),
        )
        text = beancount.entries_to_string(preamble)
        return text

    def get_beancount_name_for_account(self, account: LedgerAccount) -> str:
        """
        get the beancount name for the ledger account name
        """
        self.account_type_map = {
            "ROOT": "Equity",
            "BANK": "Assets",
            "EXPENSE": "Expenses",
            "INCOME": "Income",
            "LIABILITY": "Liabilities",
            "EQUITY": "Equity",
            "ASSET": "Assets",
        }
        prefix = self.account_type_map.get(account.account_type, "Expenses")
        fq_name = self.lbook.fq_account_name(account)
        fq_name = self.beancount.sanitize_account_name(fq_name)
        if fq_name in self.account_type_map.keys():
            return None
        beancount_account_name = f"{prefix}:{fq_name}"
        return beancount_account_name

    def convert_account(self, account: LedgerAccount) -> Optional[data.Open]:
        """
        Convert a ledger account to a Beancount Open directive.

        Args:
            account (LedgerAccount): The ledger account to convert.

        Returns:
            Optional[data.Open]: The Beancount Open directive, or None if conversion fails.
        """
        currencies = [account.currency] if account.currency else []
        beancount_account_name = self.get_beancount_name_for_account(account)
        if not beancount_account_name:
            return None
        od = self.beancount.create_open_directive(
            fq_account_name=beancount_account_name,
            date=self.start_date,
            currencies=currencies,
            meta={"description": account.description} if account.description else None,
        )
        return od

    def convert_transaction(
        self, transaction: LedgerTransaction
    ) -> Optional[data.Transaction]:
        """
        Convert a ledger transaction to a Beancount Transaction directive.

        Args:
            transaction (Transaction): The ledger transaction to convert.

        Returns:
            Optional[data.Transaction]: The Beancount Transaction directive, or None if conversion fails.
        """
        date = None
        if transaction.isodate:
            date = DateUtils.parse_date(transaction.isodate)
        if date is None:
            self.log.log(
                "⚠️", "date_parse", f"Unable to parse date: {transaction.isodate}"
            )
            return None

        postings = []
        for split in transaction.splits:
            if split.account_id not in self.lbook.accounts:
                self.log.log(
                    "❌", "split", f"invalid split account: {split.account_id}"
                )
                continue
            split_account = self.lbook.accounts[split.account_id]
            beancount_account_name = self.get_beancount_name_for_account(split_account)
            posting_meta = {"vat_code": split.vat_code} if split.vat_code else None
            postings.append(
                (
                    beancount_account_name,
                    split.amount,
                    split_account.currency or "EUR",
                    posting_meta,
                )
            )

        if not postings:
            self.log.log(
                "⚠️",
                "transaction_skip",
                f"Skipping transaction with no valid postings: {transaction.description}",
            )
            return None

        tx = self.beancount.create_transaction(
            date=date,
            description=transaction.description,
            postings=postings,
            payee=getattr(transaction, "payee", None),
            metadata={"memo": transaction.memo} if transaction.memo else None,
        )
        return tx

__init__(debug=False)

Constructor for Ledger Book to Beancount conversion.

Parameters:

Name Type Description Default
debug bool

Whether to enable debug logging.

False
Source code in nomina/beancount_ledger.py
127
128
129
130
131
132
133
134
135
136
137
138
139
140
def __init__(self, debug: bool = False):
    """
    Constructor for Ledger Book to Beancount conversion.

    Args:
        debug (bool): Whether to enable debug logging.
    """
    super().__init__(to_format_acronym="BEAN", debug=debug)

    # Initialize instance variables
    self.lbook = None
    self.lbook_stats = None
    self.start_date = None
    self.beancount = None

convert_account(account)

Convert a ledger account to a Beancount Open directive.

Parameters:

Name Type Description Default
account Account

The ledger account to convert.

required

Returns:

Type Description
Optional[Open]

Optional[data.Open]: The Beancount Open directive, or None if conversion fails.

Source code in nomina/beancount_ledger.py
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
def convert_account(self, account: LedgerAccount) -> Optional[data.Open]:
    """
    Convert a ledger account to a Beancount Open directive.

    Args:
        account (LedgerAccount): The ledger account to convert.

    Returns:
        Optional[data.Open]: The Beancount Open directive, or None if conversion fails.
    """
    currencies = [account.currency] if account.currency else []
    beancount_account_name = self.get_beancount_name_for_account(account)
    if not beancount_account_name:
        return None
    od = self.beancount.create_open_directive(
        fq_account_name=beancount_account_name,
        date=self.start_date,
        currencies=currencies,
        meta={"description": account.description} if account.description else None,
    )
    return od

convert_to_target()

Convert the ledger book to a Beancount object. Args: lbook (LedgerBook): The ledger book to convert.

Returns:

Name Type Description
Beancount Beancount

The converted Beancount object.

Source code in nomina/beancount_ledger.py
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def convert_to_target(self) -> Beancount:
    """
    Convert the ledger book to a Beancount object.
    Args:
        lbook (LedgerBook): The ledger book to convert.

    Returns:
        Beancount: The converted Beancount object.
    """
    self.lbook = self.source
    self.lbook_stats = self.lbook.get_stats()
    self.start_date = self.lbook.get_stats().start_date or DateUtils.iso_date(
        datetime.now()
    )
    self.beancount = Beancount()

    for account in self.lbook.accounts.values():
        self.beancount.add_entry(self.convert_account(account))

    for transaction in self.lbook.transactions.values():
        self.beancount.add_entry(self.convert_transaction(transaction))

    self.target = self.beancount
    return self.beancount

convert_transaction(transaction)

Convert a ledger transaction to a Beancount Transaction directive.

Parameters:

Name Type Description Default
transaction Transaction

The ledger transaction to convert.

required

Returns:

Type Description
Optional[Transaction]

Optional[data.Transaction]: The Beancount Transaction directive, or None if conversion fails.

Source code in nomina/beancount_ledger.py
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
def convert_transaction(
    self, transaction: LedgerTransaction
) -> Optional[data.Transaction]:
    """
    Convert a ledger transaction to a Beancount Transaction directive.

    Args:
        transaction (Transaction): The ledger transaction to convert.

    Returns:
        Optional[data.Transaction]: The Beancount Transaction directive, or None if conversion fails.
    """
    date = None
    if transaction.isodate:
        date = DateUtils.parse_date(transaction.isodate)
    if date is None:
        self.log.log(
            "⚠️", "date_parse", f"Unable to parse date: {transaction.isodate}"
        )
        return None

    postings = []
    for split in transaction.splits:
        if split.account_id not in self.lbook.accounts:
            self.log.log(
                "❌", "split", f"invalid split account: {split.account_id}"
            )
            continue
        split_account = self.lbook.accounts[split.account_id]
        beancount_account_name = self.get_beancount_name_for_account(split_account)
        posting_meta = {"vat_code": split.vat_code} if split.vat_code else None
        postings.append(
            (
                beancount_account_name,
                split.amount,
                split_account.currency or "EUR",
                posting_meta,
            )
        )

    if not postings:
        self.log.log(
            "⚠️",
            "transaction_skip",
            f"Skipping transaction with no valid postings: {transaction.description}",
        )
        return None

    tx = self.beancount.create_transaction(
        date=date,
        description=transaction.description,
        postings=postings,
        payee=getattr(transaction, "payee", None),
        metadata={"memo": transaction.memo} if transaction.memo else None,
    )
    return tx

get_beancount_name_for_account(account)

get the beancount name for the ledger account name

Source code in nomina/beancount_ledger.py
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def get_beancount_name_for_account(self, account: LedgerAccount) -> str:
    """
    get the beancount name for the ledger account name
    """
    self.account_type_map = {
        "ROOT": "Equity",
        "BANK": "Assets",
        "EXPENSE": "Expenses",
        "INCOME": "Income",
        "LIABILITY": "Liabilities",
        "EQUITY": "Equity",
        "ASSET": "Assets",
    }
    prefix = self.account_type_map.get(account.account_type, "Expenses")
    fq_name = self.lbook.fq_account_name(account)
    fq_name = self.beancount.sanitize_account_name(fq_name)
    if fq_name in self.account_type_map.keys():
        return None
    beancount_account_name = f"{prefix}:{fq_name}"
    return beancount_account_name

load(input_path)

load the Ledger Book

Returns:

Name Type Description
LedgerBook Book

the ledger book

Source code in nomina/beancount_ledger.py
142
143
144
145
146
147
148
149
150
151
def load(self, input_path: str) -> LedgerBook:
    """
    load the Ledger Book

    Returns:
        LedgerBook: the ledger book
    """
    lbook = LedgerBook.load_from_yaml_file(input_path)  # # @UndefinedVariable
    self.set_source(lbook)
    return lbook

beanquery_cmd

Created on 2024-11-02

@author: wf

BeanQueryCmd

Bases: QueryCmd

Extended version of QueryCmd to support named parameterized queries for beanquery

Source code in nomina/beanquery_cmd.py
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
class BeanQueryCmd(QueryCmd):
    """
    Extended version of QueryCmd to support
    named parameterized queries for beanquery
    """

    def __init__(self, args: Namespace):
        args.language = "sql"
        super().__init__(args, with_default_queries=False)

    def handle_args(self) -> bool:
        """
        Handle the command line arguments, ensure the query is loaded and parameters are parsed.
        """
        # Call the superclass method to handle basic argument parsing
        handled = super().handle_args()

        if self.queryCode:
            # Parameters should have already been parsed and applied in the base class
            if self.args.debug or self.args.showQuery:
                print(f"Final query after parameter substitution:\n{self.query.query}")
            endpoint = self.endpoints.get(self.args.endpointName)
            if not endpoint:
                raise ValueError(f"unknown endpoint {self.args.endpointName}")
            query_handler = BeanQueryHandler(beancount_file=endpoint.endpoint)
            qlod = query_handler.execute_query(self.queryCode)
            self.format_output(qlod)
        return handled

handle_args()

Handle the command line arguments, ensure the query is loaded and parameters are parsed.

Source code in nomina/beanquery_cmd.py
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def handle_args(self) -> bool:
    """
    Handle the command line arguments, ensure the query is loaded and parameters are parsed.
    """
    # Call the superclass method to handle basic argument parsing
    handled = super().handle_args()

    if self.queryCode:
        # Parameters should have already been parsed and applied in the base class
        if self.args.debug or self.args.showQuery:
            print(f"Final query after parameter substitution:\n{self.query.query}")
        endpoint = self.endpoints.get(self.args.endpointName)
        if not endpoint:
            raise ValueError(f"unknown endpoint {self.args.endpointName}")
        query_handler = BeanQueryHandler(beancount_file=endpoint.endpoint)
        qlod = query_handler.execute_query(self.queryCode)
        self.format_output(qlod)
    return handled

main(argv=None)

Main entry point for the npbeanquery script.

Source code in nomina/beanquery_cmd.py
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def main(argv: list = None):
    """
    Main entry point for the npbeanquery script.
    """
    parser = ArgumentParser(
        description="BeanQuery command-line tool with extended features"
    )
    BeanQueryCmd.add_args(parser)
    # @FIXME - redundannt argument handling
    parser.add_argument(
        "-en",
        "--endpointName",
        default="example_beancount",
        help=f"Name of the endpoint to use for queries. - use -el option to list available endpoints",
    )
    parser.add_argument("-f", "--format", type=Format, choices=list(Format))

    args = parser.parse_args(argv)

    cmd = BeanQueryCmd(args)
    handled = cmd.handle_args()

    # Query execution should be done by handle_args() or subsequent method calls
    return 0 if handled else 1

book_view

Created on 2024-10-12

@author: wf

BookView

view a Ledger Book (of any accounting file format)

Source code in nomina/book_view.py
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
class BookView:
    """
    view a Ledger Book (of any accounting file format)
    """

    def __init__(self, solution: InputWebSolution):
        """
        constructor
        """
        self.solution = solution
        self.is_local = self.solution.is_local
        self.file_formats = AccountingFileFormats()
        self.file_path = None
        self.summary_card = None

    async def load_book(self):
        """
        load Ledger Book
        """
        try:
            self.summary_row.clear()
            with self.summary_row:
                ui.notify(f"loading {self.file_path}...")
                self.file_format = self.file_formats.detect_format(self.file_path)

                if not self.file_format:
                    ui.notify("could not detect file format")
                    return

                if self.file_format.acronym == "LB-YAML":
                    self.book = LedgerBook.load_from_yaml_file(self.file_path)
                elif self.file_format.acronym == "BEAN":
                    bc2lg = BeancountToLedgerConverter()
                    _beancount = bc2lg.load(self.file_path)
                    self.book = bc2lg.convert_to_target()
                elif self.file_format.acronym == "MS-MONEY-ZIP":
                    m2lg = MicrosoftMoneyToLedgerConverter()
                    _mszip = m2lg.load(self.file_path)
                    self.book = m2lg.convert_to_target()
                elif self.file_format.acronym == "MS-MONEY":
                    mny2zip = MnyToZipConverter()
                    mny_zip = mny2zip.export_mny_to_zip(self.file_path)
                    m2lg = MicrosoftMoneyToLedgerConverter()
                    _mszip = m2lg.load(mny_zip)
                    self.book = m2lg.convert_to_target()
                elif self.file_format.acronym == "QIF":
                    qif2lg = QifToLedgerConverter()
                    self.book = qif2lg.convert_to_ledger(self.file_path)
                elif self.file_format.acronym == "GC-XML":
                    gcx2lg = GnuCashToLedgerConverter()
                    self.book = gcx2lg.convert_to_ledger(self.file_path)
                else:
                    ui.notify(
                        f"can not handle file format {self.file_format.acronym} (yet)"
                    )
                    return
                self.stats = self.book.get_stats()
                with ui.card() as self.summary_card:
                    filename = os.path.basename(self.file_path)
                    ui.label(f"{filename} ({self.file_format.acronym})")
                    ui.label(f"{self.stats.start_date}-{self.stats.end_date}")
                    ui.label(
                        f"{self.stats.accounts} accounts, {self.stats.transactions} transactions"
                    )

                account_names = []
                for _account_id, account in self.book.accounts.items():
                    account_names.append(account.name)
                ComboBox(
                    label="account",
                    options=account_names,
                    width_chars=30,
                    clearable=True,
                    on_change=self.select_account,
                )
        except Exception as ex:
            self.solution.handle_exception(ex)

    async def select_account(self, args):
        """
        select an account
        """
        account_name = args.value
        for _account_id, account in self.book.accounts.items():
            if account_name == account.name:
                self.account_view.update(book=self.book, account=account)
        pass

    async def read_and_optionally_render(self, input_str, with_render: bool = False):
        """
        Reads the given input and optionally renders the given input

        Args:
            input_str (str): The input string representing a URL or local file.
            with_render(bool): if True also render
        """
        if with_render:
            # just to use the flag
            pass
        if os.path.isfile(input_str):
            self.file_path = input_str
            # https://github.com/zauberzeug/nicegui/discussions/2729
            self.summary_row.clear()
            with self.summary_row:
                ui.spinner()
                self.load_task = background_tasks.create(self.load_book())

    def setup_ui(self):
        """
        setup my user interface
        """
        with ui.row() as self.summary_row:
            self.book_html = ui.html("Welcome to Nomina!")
            if not self.is_local:
                extensions = {
                    "Ledgerbook": ".yaml",
                    "GnuCash": ".xml",
                    "beancount": ".beancount",
                    "MSMoney-Zip": ".zip",
                    "MSMoney": ".mny",
                    "Quicken": ".qif",
                }
                self.example_selector = FileSelector(
                    path=self.solution.root_path,
                    handler=self.read_and_optionally_render,
                    extensions=extensions,
                )
        with ui.row() as self.account_row:
            self.account_view = AccountView(self.solution, self.account_row)

__init__(solution)

constructor

Source code in nomina/book_view.py
29
30
31
32
33
34
35
36
37
def __init__(self, solution: InputWebSolution):
    """
    constructor
    """
    self.solution = solution
    self.is_local = self.solution.is_local
    self.file_formats = AccountingFileFormats()
    self.file_path = None
    self.summary_card = None

load_book() async

load Ledger Book

Source code in nomina/book_view.py
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
async def load_book(self):
    """
    load Ledger Book
    """
    try:
        self.summary_row.clear()
        with self.summary_row:
            ui.notify(f"loading {self.file_path}...")
            self.file_format = self.file_formats.detect_format(self.file_path)

            if not self.file_format:
                ui.notify("could not detect file format")
                return

            if self.file_format.acronym == "LB-YAML":
                self.book = LedgerBook.load_from_yaml_file(self.file_path)
            elif self.file_format.acronym == "BEAN":
                bc2lg = BeancountToLedgerConverter()
                _beancount = bc2lg.load(self.file_path)
                self.book = bc2lg.convert_to_target()
            elif self.file_format.acronym == "MS-MONEY-ZIP":
                m2lg = MicrosoftMoneyToLedgerConverter()
                _mszip = m2lg.load(self.file_path)
                self.book = m2lg.convert_to_target()
            elif self.file_format.acronym == "MS-MONEY":
                mny2zip = MnyToZipConverter()
                mny_zip = mny2zip.export_mny_to_zip(self.file_path)
                m2lg = MicrosoftMoneyToLedgerConverter()
                _mszip = m2lg.load(mny_zip)
                self.book = m2lg.convert_to_target()
            elif self.file_format.acronym == "QIF":
                qif2lg = QifToLedgerConverter()
                self.book = qif2lg.convert_to_ledger(self.file_path)
            elif self.file_format.acronym == "GC-XML":
                gcx2lg = GnuCashToLedgerConverter()
                self.book = gcx2lg.convert_to_ledger(self.file_path)
            else:
                ui.notify(
                    f"can not handle file format {self.file_format.acronym} (yet)"
                )
                return
            self.stats = self.book.get_stats()
            with ui.card() as self.summary_card:
                filename = os.path.basename(self.file_path)
                ui.label(f"{filename} ({self.file_format.acronym})")
                ui.label(f"{self.stats.start_date}-{self.stats.end_date}")
                ui.label(
                    f"{self.stats.accounts} accounts, {self.stats.transactions} transactions"
                )

            account_names = []
            for _account_id, account in self.book.accounts.items():
                account_names.append(account.name)
            ComboBox(
                label="account",
                options=account_names,
                width_chars=30,
                clearable=True,
                on_change=self.select_account,
            )
    except Exception as ex:
        self.solution.handle_exception(ex)

read_and_optionally_render(input_str, with_render=False) async

Reads the given input and optionally renders the given input

Parameters:

Name Type Description Default
input_str str

The input string representing a URL or local file.

required
with_render(bool)

if True also render

required
Source code in nomina/book_view.py
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
async def read_and_optionally_render(self, input_str, with_render: bool = False):
    """
    Reads the given input and optionally renders the given input

    Args:
        input_str (str): The input string representing a URL or local file.
        with_render(bool): if True also render
    """
    if with_render:
        # just to use the flag
        pass
    if os.path.isfile(input_str):
        self.file_path = input_str
        # https://github.com/zauberzeug/nicegui/discussions/2729
        self.summary_row.clear()
        with self.summary_row:
            ui.spinner()
            self.load_task = background_tasks.create(self.load_book())

select_account(args) async

select an account

Source code in nomina/book_view.py
102
103
104
105
106
107
108
109
110
async def select_account(self, args):
    """
    select an account
    """
    account_name = args.value
    for _account_id, account in self.book.accounts.items():
        if account_name == account.name:
            self.account_view.update(book=self.book, account=account)
    pass

setup_ui()

setup my user interface

Source code in nomina/book_view.py
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def setup_ui(self):
    """
    setup my user interface
    """
    with ui.row() as self.summary_row:
        self.book_html = ui.html("Welcome to Nomina!")
        if not self.is_local:
            extensions = {
                "Ledgerbook": ".yaml",
                "GnuCash": ".xml",
                "beancount": ".beancount",
                "MSMoney-Zip": ".zip",
                "MSMoney": ".mny",
                "Quicken": ".qif",
            }
            self.example_selector = FileSelector(
                path=self.solution.root_path,
                handler=self.read_and_optionally_render,
                extensions=extensions,
            )
    with ui.row() as self.account_row:
        self.account_view = AccountView(self.solution, self.account_row)

bzv

Banking ZV Subsembly json export Created on 2024-10-05

@author: wf

Book

a Banking ZV Book

Source code in nomina/bzv.py
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
@lod_storable
class Book:
    """
    a Banking ZV Book
    """

    name: str
    owner: Optional[str] = (None,)
    url: Optional[str] = (None,)
    since: Optional[str] = (None,)
    account_json_exports: Dict[str, str] = field(default_factory=dict)
    default_category = "UndefinedCategory"

    def __post_init__(self):
        self.accounts: Dict[str, Account] = {}
        self.transactions: List[Transaction] = []
        self.batches: Dict[str, List[Transaction]] = {}

    def organize_batches(self):
        """
        Organize transactions into batches
        """
        self.batches = {}
        for transaction in self.transactions:
            if not transaction.BtchId:
                self.batches[transaction.Id] = [transaction]
            else:
                if transaction.BtchId not in self.batches:
                    self.batches[transaction.BtchId] = []
                self.batches[transaction.BtchId].append(transaction)
        pass

    @classmethod
    def load_from_file(cls, filename: str) -> "Book":
        book = Book.load_from_yaml_file(filename)
        yaml_dir = os.path.dirname(filename)

        # Adjust JSON file paths to be relative to the YAML file
        for account, json_path in book.account_json_exports.items():
            book.account_json_exports[account] = os.path.join(yaml_dir, json_path)

        book.load_accounts_from_accounts_dict(book.account_json_exports)
        return book

    def get_stats(self) -> Stats:
        """
        Calculates and returns statistics related to the transactions, accounts, and other properties of the Book.

        Returns:
            Stats: An object containing various statistics about the Book.
        """
        dates = [
            datetime.strptime(tx.BookgDt, "%Y-%m-%d")
            for tx in self.transactions
            if tx.BookgDt
        ]

        currencies = {}
        categories = set()
        for tx in self.transactions:
            currencies[tx.AmtCcy] = currencies.get(tx.AmtCcy, 0) + 1
            if tx.Category:
                categories.add(tx.Category)

        return Stats(
            accounts=len(self.accounts),
            transactions=len(self.batches),
            start_date=min(dates).strftime("%Y-%m-%d") if dates else None,
            end_date=max(dates).strftime("%Y-%m-%d") if dates else None,
            categories=len(categories),
            currencies=currencies,
            other={"name": self.name, "owner": self.owner},
        )

    def load_accounts_from_accounts_dict(self, account_json_dict: dict):
        """
        Loads transactions from a dictionary of JSON file paths and populates the accounts.

        Args:
            account_json_dict (dict): A dictionary where keys are account IDs and values are paths to JSON files containing transaction data.

        """
        for bank_account, json_file in account_json_dict.items():
            # Load transactions from the JSON file
            txs = self.load_transactions_from_json_file(json_file)
            self.transactions.extend(txs)
            # get the account id from the first transaction
            account_id = txs[0].AcctId

            # Create an account object and add it to the accounts dictionary
            self.accounts[account_id] = Account(
                account_id=account_id, name=bank_account
            )

        # Create category accounts as needed
        self.create_category_accounts()
        self.organize_batches()

    def add_category_account(self, category: str):
        """
        add a category account for the given category
        """
        parts = category.split(":")
        current = ""
        parent = None
        for part in parts:
            if current:
                parent = current
                current += ":"
            current += part
            if current not in self.accounts:
                account = Account(
                    account_id=current, name=part, parent_account_id=parent
                )
                self.accounts[current] = account

    def create_category_accounts(self):
        """
        create the category accounts
        """
        self.add_category_account(self.default_category)
        for transaction in self.transactions:
            category = transaction.Category
            if category:
                self.add_category_account(category)
            else:
                transaction.Category = self.default_category

    @staticmethod
    def load_transactions_from_json_file(json_file_path: str) -> List[Transaction]:
        with open(json_file_path, "r", encoding="utf-8") as json_file:
            trecs = json.load(json_file)
            return [from_dict(Transaction, trec) for trec in trecs]

    def show_batch_histogram(self):
        # Count the occurrence of each batch size
        batch_sizes = [len(batch) for batch in self.batches.values()]
        size_count = Counter(batch_sizes)

        # Prepare data for tabulate
        table_data = [(size, count) for size, count in sorted(size_count.items())]
        headers = ["Batch Size", "Count"]

        # Print the histogram table using tabulate
        print("\nBatch Size Histogram Table:")
        print(tabulate(table_data, headers=headers, tablefmt="grid"))

add_category_account(category)

add a category account for the given category

Source code in nomina/bzv.py
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
def add_category_account(self, category: str):
    """
    add a category account for the given category
    """
    parts = category.split(":")
    current = ""
    parent = None
    for part in parts:
        if current:
            parent = current
            current += ":"
        current += part
        if current not in self.accounts:
            account = Account(
                account_id=current, name=part, parent_account_id=parent
            )
            self.accounts[current] = account

create_category_accounts()

create the category accounts

Source code in nomina/bzv.py
200
201
202
203
204
205
206
207
208
209
210
def create_category_accounts(self):
    """
    create the category accounts
    """
    self.add_category_account(self.default_category)
    for transaction in self.transactions:
        category = transaction.Category
        if category:
            self.add_category_account(category)
        else:
            transaction.Category = self.default_category

get_stats()

Calculates and returns statistics related to the transactions, accounts, and other properties of the Book.

Returns:

Name Type Description
Stats Stats

An object containing various statistics about the Book.

Source code in nomina/bzv.py
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def get_stats(self) -> Stats:
    """
    Calculates and returns statistics related to the transactions, accounts, and other properties of the Book.

    Returns:
        Stats: An object containing various statistics about the Book.
    """
    dates = [
        datetime.strptime(tx.BookgDt, "%Y-%m-%d")
        for tx in self.transactions
        if tx.BookgDt
    ]

    currencies = {}
    categories = set()
    for tx in self.transactions:
        currencies[tx.AmtCcy] = currencies.get(tx.AmtCcy, 0) + 1
        if tx.Category:
            categories.add(tx.Category)

    return Stats(
        accounts=len(self.accounts),
        transactions=len(self.batches),
        start_date=min(dates).strftime("%Y-%m-%d") if dates else None,
        end_date=max(dates).strftime("%Y-%m-%d") if dates else None,
        categories=len(categories),
        currencies=currencies,
        other={"name": self.name, "owner": self.owner},
    )

load_accounts_from_accounts_dict(account_json_dict)

Loads transactions from a dictionary of JSON file paths and populates the accounts.

Parameters:

Name Type Description Default
account_json_dict dict

A dictionary where keys are account IDs and values are paths to JSON files containing transaction data.

required
Source code in nomina/bzv.py
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def load_accounts_from_accounts_dict(self, account_json_dict: dict):
    """
    Loads transactions from a dictionary of JSON file paths and populates the accounts.

    Args:
        account_json_dict (dict): A dictionary where keys are account IDs and values are paths to JSON files containing transaction data.

    """
    for bank_account, json_file in account_json_dict.items():
        # Load transactions from the JSON file
        txs = self.load_transactions_from_json_file(json_file)
        self.transactions.extend(txs)
        # get the account id from the first transaction
        account_id = txs[0].AcctId

        # Create an account object and add it to the accounts dictionary
        self.accounts[account_id] = Account(
            account_id=account_id, name=bank_account
        )

    # Create category accounts as needed
    self.create_category_accounts()
    self.organize_batches()

organize_batches()

Organize transactions into batches

Source code in nomina/bzv.py
102
103
104
105
106
107
108
109
110
111
112
113
114
def organize_batches(self):
    """
    Organize transactions into batches
    """
    self.batches = {}
    for transaction in self.transactions:
        if not transaction.BtchId:
            self.batches[transaction.Id] = [transaction]
        else:
            if transaction.BtchId not in self.batches:
                self.batches[transaction.BtchId] = []
            self.batches[transaction.BtchId].append(transaction)
    pass

Transaction

Represents a Subsembly/Banking ZV financial transaction with detailed information about the transaction, account details, and remittance information.

Source code in nomina/bzv.py
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
@lod_storable
class Transaction:
    """
    Represents a Subsembly/Banking ZV financial transaction with detailed information about the transaction,
    account details, and remittance information.
    """

    # Transaction identifiers
    BtchId: Optional[
        str
    ]  # Batch identifier, e.g., "987654321" will be the same for all splits of a transaction
    Id: str  # Transaction identifier, e.g., "111222333"
    AcctId: str  # Account identifier, e.g., "123456789"

    # Transaction details
    Amt: str  # Transaction amount, e.g., "100.50"
    AmtCcy: str  # Currency of the amount, e.g., "USD"
    BookgDt: str  # Booking date, e.g., "2024-10-09"
    BookgSts: str  # Booking status, e.g., "BOOK"
    CdtDbtInd: str  # Credit/Debit indicator, e.g., "CRDT" for credit
    ValDt: Optional[str]  # Value date, e.g., "2024-10-09"

    # Account owner information
    OwnrAcctBIC: Optional[str]  # BIC, e.g., "ABCDEFGHXXX"
    OwnrAcctBankCode: str  # Bank code, e.g., "12345678"
    OwnrAcctCcy: str  # Account currency, e.g., "USD"
    OwnrAcctIBAN: Optional[str]  # IBAN, e.g., "DE00123456789012345678"
    OwnrAcctNo: str  # Account number, e.g., "1234567890"

    # Remittance information
    RmtdAcctBIC: Optional[str]  # BIC, e.g., "ZYXWVUTSRQP"
    RmtdAcctCtry: Optional[str]  # Country, e.g., "US"
    RmtdAcctIBAN: Optional[str]  # IBAN, e.g., "US00987654321098765432"
    RmtdNm: Optional[str]  # Name, e.g., "Tech Solutions Inc."
    RmtdUltmtNm: Optional[
        str
    ]  # Ultimate name, e.g., "Global Tech Solutions Corporation"

    # Additional transaction information
    BankRef: Optional[str]  # Bank reference number
    BkTxCd: Optional[str]  # Bank transaction code
    BookgTxt: Optional[str]  # Booking text or description
    BtchBookg: Optional[bool]  # Whether part of a batch booking, e.g., False
    Category: Optional[str]  # Transaction category, e.g., "1780 Sales Tax"
    CdtrId: Optional[str]  # Creditor identifier
    Flag: str  # Transaction flag, e.g., "None"
    GVC: Optional[str]  # German 'Geschäftsvorfallcode' (business transaction code)
    Notes: Optional[
        str
    ]  # Additional notes, e.g., "Ref: INV-2024-001 / Training Service EREF: 1234567890 ABWA: Technology Services Ltd"
    PrimaNotaNo: Optional[str]  # Prima nota number
    ReadStatus: bool  # Whether the transaction has been read, e.g., True
    RmtInf: Optional[str]  # Remittance information

bzv_ledger

Created on 2024-10-05

@author: wf

BankingZVToLedgerConverter

Bases: BaseToLedgerConverter

convert BankingZV Entries to Ledger format

Source code in nomina/bzv_ledger.py
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
class BankingZVToLedgerConverter(BaseToLedgerConverter):
    """
    convert BankingZV Entries to Ledger format
    """

    def __init__(self, debug: bool = False):
        """
        Constructor for BankingZV to Ledger Book conversion.

        Args:
            debug (bool): Whether to enable debug logging.
        """
        super().__init__(from_format_acronym="BZV-YAML", debug=debug)

    def load(self, input_path: Path) -> BzvBook:
        """
        load the book
        """
        bzv_book = BzvBook.load_from_file(input_path)
        self.set_source(bzv_book)
        return bzv_book

    def set_source(self, bzv_book: BzvBook):
        self.bzv_book = bzv_book
        self.source = self.bzv_book
        return self.source

    def map_account_type(self, bzv_account: Account) -> str:
        """
        get the account type
        """
        account_type = "CATEGORY"
        if bzv_account.parent_account_id is None:
            # name is a pure number
            if re.fullmatch(r"\d+", bzv_account.name):
                account_type = "BANK"
        return account_type

    def create_ledger_account(self, bzv_account: Account) -> LedgerAccount:
        """
        create a ledger account from a banking ZV account
        """
        account_type = self.map_account_type(bzv_account)
        account = LedgerAccount(
            account_id=bzv_account.account_id,
            name=bzv_account.name,
            account_type=account_type,
            description=f"",
            currency="EUR",
            parent_account_id=bzv_account.parent_account_id,
        )
        return account

    def create_ledger_splits(self, transaction: BzvTransaction) -> List[LedgerSplit]:
        """
        create the ledger split
        """
        amount = float(transaction.Amt)
        # CRDT or DBIT?
        if transaction.CdtDbtInd == "DBIT":
            amount = -amount

        splits = [
            LedgerSplit(
                amount=amount,
                account_id=transaction.AcctId,
                memo=transaction.RmtInf or "",
            )
        ]

        if transaction.Category:
            splits.append(
                LedgerSplit(
                    amount=-amount,
                    account_id=transaction.Category,
                    memo=transaction.RmtInf or "",
                )
            )
        else:
            pass

        return splits

    def create_batch_transaction(
        self, batch_id: str, batch_transactions: List[BzvTransaction]
    ) -> LedgerTransaction:
        """
        Create a single ledger transaction for a batch of BZV transactions
        """
        is_split = len(batch_transactions) > 1 and batch_id is not None
        first_tx = batch_transactions[0]
        memo = f"{batch_id}"
        if is_split:
            description = first_tx.Notes
            payee = first_tx.RmtdNm
        else:
            description = first_tx.RmtInf
            payee = first_tx.RmtdNm
            delim = "->"
            if first_tx.BookgTxt:
                memo += f"{delim}{first_tx.BookgTxt}"
            if first_tx.CdtrId:
                memo += f"{delim}{first_tx.CdtrId}"
        splits = []
        for tx in batch_transactions:
            splits.extend(self.create_ledger_splits(tx))

        lt = LedgerTransaction(
            isodate=first_tx.BookgDt,
            payee=payee,
            description=description,
            splits=splits,
            memo=memo,
        )
        return lt

    def convert_to_target(self) -> LedgerBook:
        """
        convert my Banking ZV book to a ledger book
        """
        ledger_book = LedgerBook(
            owner=self.bzv_book.owner, url=self.bzv_book.url, name=self.bzv_book.name
        )

        for bzv_account in self.bzv_book.accounts.values():
            ledger_account = self.create_ledger_account(bzv_account)
            ledger_book.accounts[ledger_account.account_id] = ledger_account

        # Process all batches (including single-transaction "batches")
        for batch_id, batch_transactions in self.bzv_book.batches.items():
            ledger_transaction = self.create_batch_transaction(
                batch_id, batch_transactions
            )
            transaction_id = f"{ledger_transaction.isodate}:{batch_id}"
            ledger_book.transactions[transaction_id] = ledger_transaction

        self.target = ledger_book
        return ledger_book

    def to_text(self) -> str:
        yaml_str = self.target.to_yaml()
        return yaml_str

__init__(debug=False)

Constructor for BankingZV to Ledger Book conversion.

Parameters:

Name Type Description Default
debug bool

Whether to enable debug logging.

False
Source code in nomina/bzv_ledger.py
26
27
28
29
30
31
32
33
def __init__(self, debug: bool = False):
    """
    Constructor for BankingZV to Ledger Book conversion.

    Args:
        debug (bool): Whether to enable debug logging.
    """
    super().__init__(from_format_acronym="BZV-YAML", debug=debug)

convert_to_target()

convert my Banking ZV book to a ledger book

Source code in nomina/bzv_ledger.py
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def convert_to_target(self) -> LedgerBook:
    """
    convert my Banking ZV book to a ledger book
    """
    ledger_book = LedgerBook(
        owner=self.bzv_book.owner, url=self.bzv_book.url, name=self.bzv_book.name
    )

    for bzv_account in self.bzv_book.accounts.values():
        ledger_account = self.create_ledger_account(bzv_account)
        ledger_book.accounts[ledger_account.account_id] = ledger_account

    # Process all batches (including single-transaction "batches")
    for batch_id, batch_transactions in self.bzv_book.batches.items():
        ledger_transaction = self.create_batch_transaction(
            batch_id, batch_transactions
        )
        transaction_id = f"{ledger_transaction.isodate}:{batch_id}"
        ledger_book.transactions[transaction_id] = ledger_transaction

    self.target = ledger_book
    return ledger_book

create_batch_transaction(batch_id, batch_transactions)

Create a single ledger transaction for a batch of BZV transactions

Source code in nomina/bzv_ledger.py
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
def create_batch_transaction(
    self, batch_id: str, batch_transactions: List[BzvTransaction]
) -> LedgerTransaction:
    """
    Create a single ledger transaction for a batch of BZV transactions
    """
    is_split = len(batch_transactions) > 1 and batch_id is not None
    first_tx = batch_transactions[0]
    memo = f"{batch_id}"
    if is_split:
        description = first_tx.Notes
        payee = first_tx.RmtdNm
    else:
        description = first_tx.RmtInf
        payee = first_tx.RmtdNm
        delim = "->"
        if first_tx.BookgTxt:
            memo += f"{delim}{first_tx.BookgTxt}"
        if first_tx.CdtrId:
            memo += f"{delim}{first_tx.CdtrId}"
    splits = []
    for tx in batch_transactions:
        splits.extend(self.create_ledger_splits(tx))

    lt = LedgerTransaction(
        isodate=first_tx.BookgDt,
        payee=payee,
        description=description,
        splits=splits,
        memo=memo,
    )
    return lt

create_ledger_account(bzv_account)

create a ledger account from a banking ZV account

Source code in nomina/bzv_ledger.py
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def create_ledger_account(self, bzv_account: Account) -> LedgerAccount:
    """
    create a ledger account from a banking ZV account
    """
    account_type = self.map_account_type(bzv_account)
    account = LedgerAccount(
        account_id=bzv_account.account_id,
        name=bzv_account.name,
        account_type=account_type,
        description=f"",
        currency="EUR",
        parent_account_id=bzv_account.parent_account_id,
    )
    return account

create_ledger_splits(transaction)

create the ledger split

Source code in nomina/bzv_ledger.py
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def create_ledger_splits(self, transaction: BzvTransaction) -> List[LedgerSplit]:
    """
    create the ledger split
    """
    amount = float(transaction.Amt)
    # CRDT or DBIT?
    if transaction.CdtDbtInd == "DBIT":
        amount = -amount

    splits = [
        LedgerSplit(
            amount=amount,
            account_id=transaction.AcctId,
            memo=transaction.RmtInf or "",
        )
    ]

    if transaction.Category:
        splits.append(
            LedgerSplit(
                amount=-amount,
                account_id=transaction.Category,
                memo=transaction.RmtInf or "",
            )
        )
    else:
        pass

    return splits

load(input_path)

load the book

Source code in nomina/bzv_ledger.py
35
36
37
38
39
40
41
def load(self, input_path: Path) -> BzvBook:
    """
    load the book
    """
    bzv_book = BzvBook.load_from_file(input_path)
    self.set_source(bzv_book)
    return bzv_book

map_account_type(bzv_account)

get the account type

Source code in nomina/bzv_ledger.py
48
49
50
51
52
53
54
55
56
57
def map_account_type(self, bzv_account: Account) -> str:
    """
    get the account type
    """
    account_type = "CATEGORY"
    if bzv_account.parent_account_id is None:
        # name is a pure number
        if re.fullmatch(r"\d+", bzv_account.name):
            account_type = "BANK"
    return account_type

converter

Created on 2024-10-06

@author: wf

Converter

General converter for personal accounting formats using hub and spoke model

Source code in nomina/converter.py
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class Converter:
    """
    General converter for personal accounting formats using hub and spoke model
    """

    def __init__(self, args):
        self.args = args
        self.detector = AccountingFileFormats()
        self.to_ledger: Dict[str, Type[BaseToLedgerConverter]] = {
            "GC-XML": GnuCashToLedgerConverter,
            "QIF": QifToLedgerConverter,
            # Finanzmanager Deluxe exports are QIF with !Option:MDY and class/category markup
            "FMD": QifToLedgerConverter,
            "BEAN": BeancountToLedgerConverter,
            "BZV-YAML": BankingZVToLedgerConverter,
            "MONEY": MicrosoftMoneyToLedgerConverter,
            "LB-YAML": None,
        }
        self.from_ledger: Dict[str, Type[BaseFromLedgerConverter]] = {
            "GC-XML": LedgerToGnuCashConverter,
            "BEAN": LedgerToBeancountConverter,
            "LB-YAML": None,
        }

    def convert(self, input_path: Path = None, output_format: str = None) -> None:
        """
        Convert the input file to the specified output format.

        Args:
            input_path (str, optional): Path to the input file. Defaults to None.
            output_format (str, optional): Acronym of the output format. Defaults to None.
        """
        if input_path is None:
            input_path = self.args.convert
        if output_format is None:
            output_format = self.args.format

        input_format = self.detector.detect_format(input_path)

        if not input_format:
            raise ValueError(
                f"Unsupported or unrecognized input format for file: {input_path}"
            )

        if input_format.acronym not in self.to_ledger:
            raise ValueError(f"Unsupported input format: {input_format.acronym}")
        if output_format not in self.from_ledger:
            raise ValueError(f"Unsupported output format: {output_format}")

        to_ledger_cls = self.to_ledger[input_format.acronym]
        from_ledger_cls = self.from_ledger[output_format]

        # Convert to LedgerBook
        if to_ledger_cls is QifToLedgerConverter:
            vat_codes_path = getattr(self.args, "vat_codes", None)
            vat_codes = VatCodes.of_yaml(
                str(vat_codes_path) if vat_codes_path else None
            )
            to_ledger = to_ledger_cls(debug=self.args.debug, vat_codes=vat_codes)
            ledger_book = to_ledger.convert_to_ledger(input_path)
        elif to_ledger_cls is not None:
            to_ledger = to_ledger_cls(debug=self.args.debug)
            ledger_book = to_ledger.convert_to_ledger(input_path)
        else:
            # If input is already LedgerBook, just load it
            ledger_book = Book.load_from_yaml_file(input_path)

        # Convert from LedgerBook to output format
        if from_ledger_cls is not None:
            from_ledger = from_ledger_cls(debug=self.args.debug)
            _target_object = from_ledger.convert_from_ledger(ledger_book)
            output_text = from_ledger.to_text()
            pass
        else:
            # target is a LedgerBook get the XML markup
            output_text = ledger_book.to_yaml()
        output_stream = self.args.output.open("w")
        output_stream.write(output_text)
        output_stream.close()

    def get_supported_formats(self) -> Dict[str, list]:
        """
        Get a list of supported input and output formats

        Returns:
            Dict[str, list]: A dictionary with 'input' and 'output' keys, each containing a list of supported format acronyms
        """
        input_formats = set(self.to_ledger.keys())
        output_formats = set(self.from_ledger.keys())
        return {"input": list(input_formats), "output": list(output_formats)}

convert(input_path=None, output_format=None)

Convert the input file to the specified output format.

Parameters:

Name Type Description Default
input_path str

Path to the input file. Defaults to None.

None
output_format str

Acronym of the output format. Defaults to None.

None
Source code in nomina/converter.py
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def convert(self, input_path: Path = None, output_format: str = None) -> None:
    """
    Convert the input file to the specified output format.

    Args:
        input_path (str, optional): Path to the input file. Defaults to None.
        output_format (str, optional): Acronym of the output format. Defaults to None.
    """
    if input_path is None:
        input_path = self.args.convert
    if output_format is None:
        output_format = self.args.format

    input_format = self.detector.detect_format(input_path)

    if not input_format:
        raise ValueError(
            f"Unsupported or unrecognized input format for file: {input_path}"
        )

    if input_format.acronym not in self.to_ledger:
        raise ValueError(f"Unsupported input format: {input_format.acronym}")
    if output_format not in self.from_ledger:
        raise ValueError(f"Unsupported output format: {output_format}")

    to_ledger_cls = self.to_ledger[input_format.acronym]
    from_ledger_cls = self.from_ledger[output_format]

    # Convert to LedgerBook
    if to_ledger_cls is QifToLedgerConverter:
        vat_codes_path = getattr(self.args, "vat_codes", None)
        vat_codes = VatCodes.of_yaml(
            str(vat_codes_path) if vat_codes_path else None
        )
        to_ledger = to_ledger_cls(debug=self.args.debug, vat_codes=vat_codes)
        ledger_book = to_ledger.convert_to_ledger(input_path)
    elif to_ledger_cls is not None:
        to_ledger = to_ledger_cls(debug=self.args.debug)
        ledger_book = to_ledger.convert_to_ledger(input_path)
    else:
        # If input is already LedgerBook, just load it
        ledger_book = Book.load_from_yaml_file(input_path)

    # Convert from LedgerBook to output format
    if from_ledger_cls is not None:
        from_ledger = from_ledger_cls(debug=self.args.debug)
        _target_object = from_ledger.convert_from_ledger(ledger_book)
        output_text = from_ledger.to_text()
        pass
    else:
        # target is a LedgerBook get the XML markup
        output_text = ledger_book.to_yaml()
    output_stream = self.args.output.open("w")
    output_stream.write(output_text)
    output_stream.close()

get_supported_formats()

Get a list of supported input and output formats

Returns:

Type Description
Dict[str, list]

Dict[str, list]: A dictionary with 'input' and 'output' keys, each containing a list of supported format acronyms

Source code in nomina/converter.py
104
105
106
107
108
109
110
111
112
113
def get_supported_formats(self) -> Dict[str, list]:
    """
    Get a list of supported input and output formats

    Returns:
        Dict[str, list]: A dictionary with 'input' and 'output' keys, each containing a list of supported format acronyms
    """
    input_formats = set(self.to_ledger.keys())
    output_formats = set(self.from_ledger.keys())
    return {"input": list(input_formats), "output": list(output_formats)}

date_utils

Created on 2024-10-02

@author: wf

DateUtils

date utilities

Source code in nomina/date_utils.py
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
class DateUtils:
    """
    date utilities
    """

    @staticmethod
    def iso_date(date: datetime) -> str:
        """
        Format a datetime object to a string in 'YYYY-MM-DD' format.

        Args:
            date (datetime): The date to format.

        Returns:
            str: The formatted date as a string.
        """
        return date.strftime("%Y-%m-%d")

    @classmethod
    def parse_date(
        cls, date_str: str, date_formats: Optional[List[str]] = None
    ) -> Optional[str]:
        """
        Parse the given date string using the provided formats.

        Args:
            date_str (str): The date string to parse.
            date_formats (List[str], optional): List of date formats to try.
                If None, uses a default list of formats.

        Returns:
            Optional[str]: The parsed date in ISO format (YYYY-MM-DD) or None if parsing fails.
        """
        if date_formats is None:
            date_formats = [
                # "%m.%d.%y",
                "%d.%m.%y",
                # "%m/%d/%y",
                "%d/%m/%y",
                "%d/%m/%Y",  # 23/10/2013
                "%Y-%m-%d",
                "%Y/%m/%d",
                "%Y-%m-%d %H:%M:%S %z",  # Added to handle the GnuCash XML format
                "%m/%d/%y %H:%M:%S",  # Microsoft Money
            ]

        for date_format in date_formats:
            try:
                date_obj = datetime.strptime(date_str, date_format)
                iso_date_str = cls.iso_date(date_obj)
                return iso_date_str
            except ValueError:
                continue

        return None

    @classmethod
    def split_date_range(
        cls, start_date: str, end_date: str, num_ranges: int
    ) -> List[Tuple[str, str]]:
        """
        Splits a date range into a predefined number of sub-ranges.

        Args:
            start_date (str): The start date in "YYYY-MM-DD" format.
            end_date (str): The end date in "YYYY-MM-DD" format.
            num_ranges (int): The number of ranges to split into.

        Returns:
            List[Tuple[str, str]]: A list of tuples representing the sub-ranges.
        """
        start = datetime.strptime(start_date, "%Y-%m-%d")
        end = datetime.strptime(end_date, "%Y-%m-%d")
        total_days = (end - start).days

        base_range_length = total_days // num_ranges
        extra_days = total_days % num_ranges

        ranges = []
        current_start = start
        for i in range(num_ranges):
            range_length = base_range_length + (1 if i < extra_days else 0)
            current_end = current_start + timedelta(days=range_length - 1)

            ranges.append((cls.iso_date(current_start), cls.iso_date(current_end)))
            current_start = current_end + timedelta(days=1)

        # Ensure the last range ends on the specified end date
        ranges[-1] = (ranges[-1][0], end_date)

        return ranges

iso_date(date) staticmethod

Format a datetime object to a string in 'YYYY-MM-DD' format.

Parameters:

Name Type Description Default
date datetime

The date to format.

required

Returns:

Name Type Description
str str

The formatted date as a string.

Source code in nomina/date_utils.py
16
17
18
19
20
21
22
23
24
25
26
27
@staticmethod
def iso_date(date: datetime) -> str:
    """
    Format a datetime object to a string in 'YYYY-MM-DD' format.

    Args:
        date (datetime): The date to format.

    Returns:
        str: The formatted date as a string.
    """
    return date.strftime("%Y-%m-%d")

parse_date(date_str, date_formats=None) classmethod

Parse the given date string using the provided formats.

Parameters:

Name Type Description Default
date_str str

The date string to parse.

required
date_formats List[str]

List of date formats to try. If None, uses a default list of formats.

None

Returns:

Type Description
Optional[str]

Optional[str]: The parsed date in ISO format (YYYY-MM-DD) or None if parsing fails.

Source code in nomina/date_utils.py
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
@classmethod
def parse_date(
    cls, date_str: str, date_formats: Optional[List[str]] = None
) -> Optional[str]:
    """
    Parse the given date string using the provided formats.

    Args:
        date_str (str): The date string to parse.
        date_formats (List[str], optional): List of date formats to try.
            If None, uses a default list of formats.

    Returns:
        Optional[str]: The parsed date in ISO format (YYYY-MM-DD) or None if parsing fails.
    """
    if date_formats is None:
        date_formats = [
            # "%m.%d.%y",
            "%d.%m.%y",
            # "%m/%d/%y",
            "%d/%m/%y",
            "%d/%m/%Y",  # 23/10/2013
            "%Y-%m-%d",
            "%Y/%m/%d",
            "%Y-%m-%d %H:%M:%S %z",  # Added to handle the GnuCash XML format
            "%m/%d/%y %H:%M:%S",  # Microsoft Money
        ]

    for date_format in date_formats:
        try:
            date_obj = datetime.strptime(date_str, date_format)
            iso_date_str = cls.iso_date(date_obj)
            return iso_date_str
        except ValueError:
            continue

    return None

split_date_range(start_date, end_date, num_ranges) classmethod

Splits a date range into a predefined number of sub-ranges.

Parameters:

Name Type Description Default
start_date str

The start date in "YYYY-MM-DD" format.

required
end_date str

The end date in "YYYY-MM-DD" format.

required
num_ranges int

The number of ranges to split into.

required

Returns:

Type Description
List[Tuple[str, str]]

List[Tuple[str, str]]: A list of tuples representing the sub-ranges.

Source code in nomina/date_utils.py
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@classmethod
def split_date_range(
    cls, start_date: str, end_date: str, num_ranges: int
) -> List[Tuple[str, str]]:
    """
    Splits a date range into a predefined number of sub-ranges.

    Args:
        start_date (str): The start date in "YYYY-MM-DD" format.
        end_date (str): The end date in "YYYY-MM-DD" format.
        num_ranges (int): The number of ranges to split into.

    Returns:
        List[Tuple[str, str]]: A list of tuples representing the sub-ranges.
    """
    start = datetime.strptime(start_date, "%Y-%m-%d")
    end = datetime.strptime(end_date, "%Y-%m-%d")
    total_days = (end - start).days

    base_range_length = total_days // num_ranges
    extra_days = total_days % num_ranges

    ranges = []
    current_start = start
    for i in range(num_ranges):
        range_length = base_range_length + (1 if i < extra_days else 0)
        current_end = current_start + timedelta(days=range_length - 1)

        ranges.append((cls.iso_date(current_start), cls.iso_date(current_end)))
        current_start = current_end + timedelta(days=1)

    # Ensure the last range ends on the specified end date
    ranges[-1] = (ranges[-1][0], end_date)

    return ranges

file_formats

Created on 2024-10-06

@author: wf

AccountingFileFormat dataclass

A personal account file format

Source code in nomina/file_formats.py
17
18
19
20
21
22
23
24
25
26
27
28
29
@dataclass
class AccountingFileFormat:
    """
    A personal account file format
    """

    name: str
    acronym: str
    ext: str
    wikidata_id: str
    content_pattern: str
    pattern_file: Optional[str] = None
    encoding: str = "utf-8"

AccountingFileFormats

Detector for various accounting file formats

Source code in nomina/file_formats.py
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
class AccountingFileFormats:
    """
    Detector for various accounting file formats
    """

    def __init__(self, debug: bool = False):
        self.debug = debug
        self.formats: List[AccountingFileFormat] = [
            AccountingFileFormat(
                name="Beancount",
                acronym="BEAN",
                ext=".beancount",
                wikidata_id="Q130456404",
                content_pattern=r'option "title"',
            ),
            AccountingFileFormat(
                name="GnuCash XML",
                acronym="GC-XML",
                ext=".gnucash",
                wikidata_id="Q130445392",
                content_pattern=r"<gnc-v2",
            ),
            AccountingFileFormat(
                name="GnuCash SQLite",
                acronym="GC-SQLITE",
                ext=".gnucash",
                wikidata_id="Q130445392",
                content_pattern=r"SQLite format 3",
            ),
            AccountingFileFormat(
                name="Microsoft Money - Zipped JSON dumps",
                acronym="MS-MONEY-ZIP",
                ext=".zip",
                wikidata_id="Q117428",
                pattern_file="nomina.yaml",
                content_pattern=r"NOMINA-MICROSOFT-MONEY-YAML",
                encoding="utf-8",
            ),
            AccountingFileFormat(
                name="Microsoft Money",
                acronym="MS-MONEY",
                ext=".mny",
                wikidata_id="Q117428",
                content_pattern=r"",
                encoding="utf-8",
            ),
            AccountingFileFormat(
                name="pyNomina Ledger Book YAML",
                acronym="LB-YAML",
                ext=".yaml",
                wikidata_id="Q281876",
                content_pattern=r"file_type:\s*NOMINA-LEDGER-BOOK-YAML",
            ),
            AccountingFileFormat(
                name="FinanzmanagerDeluxe",
                acronym="FMD",
                ext=".qif",
                wikidata_id="Q750657",
                content_pattern=r"!Option:MDY",
                encoding="iso-8859-1",
            ),
            AccountingFileFormat(
                name="Quicken Interchange Format",
                acronym="QIF",
                ext=".qif",
                wikidata_id="Q750657",
                content_pattern=r"(?:\^.*?){5}",  # at least five ^ entries
            ),
            AccountingFileFormat(
                name="Subsembly JSON",
                acronym="BZV-JSON",
                ext=".json",
                wikidata_id="Q130443951",
                content_pattern=r'"AcctId":\s*"[^"]+".*"OwnrAcctCcy":\s*"[^"]+"',
            ),
            AccountingFileFormat(
                name="pyNomina Banking ZV YAML export",
                acronym="BZV-YAML",
                ext=".yaml",
                wikidata_id="Q281876",
                content_pattern=r"account_json_exports\s*:",
            ),
        ]
        self.format_by_acronym: Dict[str, AccountingFileFormat] = {
            fformat.acronym: fformat for fformat in self.formats
        }

    def get_by_acronym(self, acronym: str) -> "AccountingFileFormat":
        """
        get format by acronym
        """
        return self.format_by_acronym.get(acronym)

    def detect_format(self, file_path: str) -> Optional[AccountingFileFormat]:
        """
        Detect the accounting file format based on content and extension
        """
        _, file_extension = os.path.splitext(file_path)

        if file_extension.lower() == ".zip":
            return self._detect_from_zip(file_path)
        else:
            return self._detect_from_regular_file(file_path)

    def _detect_from_zip(self, zip_path: str) -> Optional[AccountingFileFormat]:
        """
        Detect accounting file format by looking inside the zip file.
        """
        with zipfile.ZipFile(zip_path, "r") as zip_file:
            for fformat in self.formats:
                # Check if the format has a pattern_file defined
                if (
                    fformat.ext == ".zip"
                    and fformat.pattern_file in zip_file.namelist()
                ):
                    content = self._extract_file_content_from_zip(
                        zip_file, fformat.pattern_file
                    )
                    if content and self._match_pattern(
                        content, fformat.content_pattern
                    ):
                        return fformat
        return None

    def _extract_file_content_from_zip(
        self, zip_file: zipfile.ZipFile, pattern_file: str
    ) -> Optional[str]:
        """
        Extract the content of a specific file within a zip and decode it.
        """
        with zip_file.open(pattern_file) as file:
            raw_data = file.read()
            return self._decode_content(raw_data)

    def _detect_from_regular_file(
        self, file_path: str
    ) -> Optional[AccountingFileFormat]:
        """
        Detect accounting file format from a regular non-zip file.
        """
        with open(file_path, "rb") as file:
            raw_data = file.read(10000)  # Read the first 10000 bytes
        if raw_data[:2] == b"\x1f\x8b":
            # gzipped e.g. GnuCash XML saved compressed, see issue #31
            with gzip.open(file_path, "rb") as file:
                raw_data = file.read(10000)
        content = self._decode_content(raw_data)

        if content:
            for fformat in self.formats:
                _name, ext = os.path.splitext(file_path)
                if ext.lower() == fformat.ext.lower():
                    match = self._match_pattern(content, fformat.content_pattern)
                    if match:
                        return fformat
        return None

    def _decode_content(self, raw_data: bytes) -> Optional[str]:
        """
        Detect the encoding of the raw data and decode it into a string.
        """
        result = chardet.detect(raw_data)
        # chardet returns None as encoding for undetectable e.g. binary content
        encoding = result.get("encoding") or "utf-8"
        try:
            return raw_data.decode(encoding)
        except UnicodeDecodeError:
            return raw_data.decode("latin-1", errors="ignore")

    def _match_pattern(self, content: str, pattern: str) -> bool:
        """
        Check if the content matches the given pattern.
        """
        return bool(re.search(pattern, content, re.DOTALL | re.IGNORECASE))

detect_format(file_path)

Detect the accounting file format based on content and extension

Source code in nomina/file_formats.py
125
126
127
128
129
130
131
132
133
134
def detect_format(self, file_path: str) -> Optional[AccountingFileFormat]:
    """
    Detect the accounting file format based on content and extension
    """
    _, file_extension = os.path.splitext(file_path)

    if file_extension.lower() == ".zip":
        return self._detect_from_zip(file_path)
    else:
        return self._detect_from_regular_file(file_path)

get_by_acronym(acronym)

get format by acronym

Source code in nomina/file_formats.py
119
120
121
122
123
def get_by_acronym(self, acronym: str) -> "AccountingFileFormat":
    """
    get format by acronym
    """
    return self.format_by_acronym.get(acronym)

gnc_ledger

Created on 2024-10-04

@author: wf

GnuCashToLedgerConverter

Bases: BaseToLedgerConverter

Convert GnuCash Book to Ledger Book

Source code in nomina/gnc_ledger.py
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
class GnuCashToLedgerConverter(BaseToLedgerConverter):
    """
    Convert GnuCash Book to Ledger Book
    """

    def __init__(self, debug: bool = False):
        """
        constructor
        """
        super().__init__(from_format_acronym="GC-XML", debug=debug)
        self.gnc_v2 = None
        self.account_map: Dict[str, LedgerAccount] = {}
        self.gcxml = GnuCashXml()

    def load(self, input_path: str) -> GncV2:
        """
        Load the GnuCash XML file from the input file and parse it into a GncV2 object.

        Args:
            input_path (str): The input path to read the GnuCash XML data from.

        Returns:
            GncV2: The parsed GncV2 object.
        """
        self.gnc_v2 = self.gcxml.parse_gnucash_xml(input_path)
        return self.gnc_v2

    def create_ledger_account(self, gnc_account: Account) -> LedgerAccount:
        """Create a Ledger account from a GnuCash account."""
        account_id = gnc_account.id.value
        parent_account_id = gnc_account.parent.value if gnc_account.parent else None

        ledger_account = LedgerAccount(
            account_id=account_id,
            name=gnc_account.name,
            account_type=gnc_account.type,
            description=gnc_account.description or "",
            currency=gnc_account.commodity.id if gnc_account.commodity else "EUR",
            parent_account_id=parent_account_id,
        )
        self.account_map[gnc_account.id.value] = ledger_account
        return ledger_account

    def create_ledger_split(self, gnc_split: Split) -> LedgerSplit:
        """Create a Ledger split from a GnuCash split."""
        amount = (
            float(gnc_split.value.split("/")[0]) / 100
        )  # Convert from cents to float
        return LedgerSplit(
            amount=amount,
            account_id=gnc_split.account.value,
            memo=gnc_split.memo or "",
            reconciled=gnc_split.reconciled_state == "y",
        )

    def create_ledger_transaction(
        self, gnc_transaction: Transaction
    ) -> LedgerTransaction:
        """Create a Ledger transaction from a GnuCash transaction."""
        ledger_splits = [
            self.create_ledger_split(split) for split in gnc_transaction.splits
        ]
        return LedgerTransaction(
            isodate=gnc_transaction.date_posted.date,
            description=gnc_transaction.description,
            splits=ledger_splits,
            memo=gnc_transaction.description,
        )

    def convert_to_target(self) -> LedgerBook:
        """Convert the GnuCash V2 structure to a Ledger Book."""
        ledger_book = LedgerBook()

        # Convert accounts
        for gnc_account in self.gnc_v2.book.accounts:
            ledger_account = self.create_ledger_account(gnc_account)
            ledger_book.accounts[ledger_account.account_id] = ledger_account

        # Convert transactions
        for gnc_transaction in self.gnc_v2.book.transactions:
            ledger_transaction = self.create_ledger_transaction(gnc_transaction)
            # the GnuCash guid - date and description are not unique, see issue #32
            if gnc_transaction.id and gnc_transaction.id.value:
                transaction_id = gnc_transaction.id.value
            else:
                transaction_id = (
                    f"{ledger_transaction.isodate}:{len(ledger_book.transactions)}"
                )
            ledger_book.transactions[transaction_id] = ledger_transaction

        return ledger_book

    def to_text(self) -> str:
        """
        create the output text
        """
        yaml_str = self.target.to_yaml()
        return yaml_str

__init__(debug=False)

constructor

Source code in nomina/gnc_ledger.py
37
38
39
40
41
42
43
44
def __init__(self, debug: bool = False):
    """
    constructor
    """
    super().__init__(from_format_acronym="GC-XML", debug=debug)
    self.gnc_v2 = None
    self.account_map: Dict[str, LedgerAccount] = {}
    self.gcxml = GnuCashXml()

convert_to_target()

Convert the GnuCash V2 structure to a Ledger Book.

Source code in nomina/gnc_ledger.py
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def convert_to_target(self) -> LedgerBook:
    """Convert the GnuCash V2 structure to a Ledger Book."""
    ledger_book = LedgerBook()

    # Convert accounts
    for gnc_account in self.gnc_v2.book.accounts:
        ledger_account = self.create_ledger_account(gnc_account)
        ledger_book.accounts[ledger_account.account_id] = ledger_account

    # Convert transactions
    for gnc_transaction in self.gnc_v2.book.transactions:
        ledger_transaction = self.create_ledger_transaction(gnc_transaction)
        # the GnuCash guid - date and description are not unique, see issue #32
        if gnc_transaction.id and gnc_transaction.id.value:
            transaction_id = gnc_transaction.id.value
        else:
            transaction_id = (
                f"{ledger_transaction.isodate}:{len(ledger_book.transactions)}"
            )
        ledger_book.transactions[transaction_id] = ledger_transaction

    return ledger_book

create_ledger_account(gnc_account)

Create a Ledger account from a GnuCash account.

Source code in nomina/gnc_ledger.py
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def create_ledger_account(self, gnc_account: Account) -> LedgerAccount:
    """Create a Ledger account from a GnuCash account."""
    account_id = gnc_account.id.value
    parent_account_id = gnc_account.parent.value if gnc_account.parent else None

    ledger_account = LedgerAccount(
        account_id=account_id,
        name=gnc_account.name,
        account_type=gnc_account.type,
        description=gnc_account.description or "",
        currency=gnc_account.commodity.id if gnc_account.commodity else "EUR",
        parent_account_id=parent_account_id,
    )
    self.account_map[gnc_account.id.value] = ledger_account
    return ledger_account

create_ledger_split(gnc_split)

Create a Ledger split from a GnuCash split.

Source code in nomina/gnc_ledger.py
75
76
77
78
79
80
81
82
83
84
85
def create_ledger_split(self, gnc_split: Split) -> LedgerSplit:
    """Create a Ledger split from a GnuCash split."""
    amount = (
        float(gnc_split.value.split("/")[0]) / 100
    )  # Convert from cents to float
    return LedgerSplit(
        amount=amount,
        account_id=gnc_split.account.value,
        memo=gnc_split.memo or "",
        reconciled=gnc_split.reconciled_state == "y",
    )

create_ledger_transaction(gnc_transaction)

Create a Ledger transaction from a GnuCash transaction.

Source code in nomina/gnc_ledger.py
87
88
89
90
91
92
93
94
95
96
97
98
99
def create_ledger_transaction(
    self, gnc_transaction: Transaction
) -> LedgerTransaction:
    """Create a Ledger transaction from a GnuCash transaction."""
    ledger_splits = [
        self.create_ledger_split(split) for split in gnc_transaction.splits
    ]
    return LedgerTransaction(
        isodate=gnc_transaction.date_posted.date,
        description=gnc_transaction.description,
        splits=ledger_splits,
        memo=gnc_transaction.description,
    )

load(input_path)

Load the GnuCash XML file from the input file and parse it into a GncV2 object.

Parameters:

Name Type Description Default
input_path str

The input path to read the GnuCash XML data from.

required

Returns:

Name Type Description
GncV2 GncV2

The parsed GncV2 object.

Source code in nomina/gnc_ledger.py
46
47
48
49
50
51
52
53
54
55
56
57
def load(self, input_path: str) -> GncV2:
    """
    Load the GnuCash XML file from the input file and parse it into a GncV2 object.

    Args:
        input_path (str): The input path to read the GnuCash XML data from.

    Returns:
        GncV2: The parsed GncV2 object.
    """
    self.gnc_v2 = self.gcxml.parse_gnucash_xml(input_path)
    return self.gnc_v2

to_text()

create the output text

Source code in nomina/gnc_ledger.py
124
125
126
127
128
129
def to_text(self) -> str:
    """
    create the output text
    """
    yaml_str = self.target.to_yaml()
    return yaml_str

LedgerToGnuCashConverter

Bases: BaseFromLedgerConverter

Convert Ledger Book to GnuCash Book

Source code in nomina/gnc_ledger.py
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
class LedgerToGnuCashConverter(BaseFromLedgerConverter):
    """
    Convert Ledger Book to GnuCash Book
    """

    def __init__(self, debug: bool = False):
        """
        Constructor for Ledger Book to GnuCash conversion.

        Args:
            debug (bool): Whether to enable debug logging.
        """
        super().__init__(to_format_acronym="GC-XML", debug=debug)

        # Initialize instance variables
        self.lbook = None
        self.account_map = {}
        self.gcxml = GnuCashXml()

    def load(self, input_path: str) -> LedgerBook:
        """
        load the Ledger Book

        Returns:
            LedgerBook: the ledger book
        """
        lbook = LedgerBook.load_from_yaml_file(input_path)
        self.set_source(lbook)
        return lbook

    def set_source(self, source: LedgerBook):
        self.source = source
        self.lbook = source

    def generate_guid(self) -> str:
        """Generate a GUID for GnuCash entities."""
        return uuid.uuid4().hex

    def create_gnucash_account(self, laccount: LedgerAccount) -> Account:
        """Create a GnuCash account from a Ledger account."""
        gnc_account = Account(
            name=laccount.name,
            id=Id(type_value="guid", value=self.generate_guid()),
            type=laccount.account_type,
            commodity=Commodity(space="CURRENCY", id=laccount.currency),
            commodity_scu=100,
            parent=(
                Id(
                    type_value="guid",
                    value=self.account_map[laccount.parent_account_id].id.value,
                )
                if laccount.parent_account_id
                else None
            ),
            description=laccount.description,
            version="2.0.0",
        )
        self.account_map[laccount.account_id] = gnc_account
        return gnc_account

    def create_gnucash_split(
        self, lsplit: LedgerSplit, transaction_currency: str
    ) -> Split:
        """Create a GnuCash split from a Ledger split."""
        split = None
        if lsplit and lsplit.amount:
            if lsplit.account_id in self.account_map:
                account_id = self.account_map[lsplit.account_id].id.value
                split = Split(
                    id=Id(type_value="guid", value=self.generate_guid()),
                    memo=lsplit.memo,
                    reconciled_state="n",
                    value=f"{int(lsplit.amount * 100)}/100",
                    quantity=f"{int(lsplit.amount * 100)}/100",
                    account=Id(type_value="guid", value=account_id),
                )
            else:
                self.log.log(
                    "❌", "split", f"unknown split account {lsplit.account_id}"
                )
        return split

    def create_gnucash_transaction(
        self, ltransaction: LedgerTransaction
    ) -> Transaction:
        """Create a GnuCash transaction from a Ledger transaction."""
        currency = Commodity(space="CURRENCY", id="EUR")  # Assuming EUR as default
        gnc_splits = []
        for lsplit in ltransaction.splits:
            split = self.create_gnucash_split(lsplit, currency.id)
            if split:
                gnc_splits.append(split)

        return Transaction(
            id=Id(type_value="guid", value=self.generate_guid()),
            currency=currency,
            date_posted=TsDate(date=ltransaction.isodate),
            date_entered=TsDate(date=ltransaction.isodate),
            description=ltransaction.description,
            splits=gnc_splits,
            slots=Slots(
                slot=Slot(
                    key="date-posted",
                    value=Value(type_value="gdate", gdate=ltransaction.isodate),
                )
            ),
            version="2.0.0",
        )

    def convert_to_target(self) -> GncV2:
        """Convert the Ledger Book to a GnuCash V2 structure."""
        self.account_map: Dict[str, Account] = {}

        # Create GnuCash accounts
        gnc_accounts = [
            self.create_gnucash_account(account)
            for account in self.lbook.accounts.values()
        ]

        # Create GnuCash transactions
        gnc_transactions = [
            self.create_gnucash_transaction(transaction)
            for transaction in self.lbook.transactions.values()
        ]

        # Create GnuCash Book
        book = Book(
            id=Id(type_value="guid", value=self.generate_guid()),
            commodities=[
                Commodity(space="CURRENCY", id="EUR")
            ],  # Assuming EUR as default
            accounts=gnc_accounts,
            transactions=gnc_transactions,
            version="2.0.0",
        )
        book.update_count_data()

        # Create GncV2
        gnc_v2 = GncV2(count_data=CountData(type_value="book", value=1), book=book)
        self.target = gnc_v2
        return gnc_v2

    def to_text(self) -> str:
        """
        convert to text
        """
        xml_string = self.gcxml.to_text(self.target)
        return xml_string

__init__(debug=False)

Constructor for Ledger Book to GnuCash conversion.

Parameters:

Name Type Description Default
debug bool

Whether to enable debug logging.

False
Source code in nomina/gnc_ledger.py
137
138
139
140
141
142
143
144
145
146
147
148
149
def __init__(self, debug: bool = False):
    """
    Constructor for Ledger Book to GnuCash conversion.

    Args:
        debug (bool): Whether to enable debug logging.
    """
    super().__init__(to_format_acronym="GC-XML", debug=debug)

    # Initialize instance variables
    self.lbook = None
    self.account_map = {}
    self.gcxml = GnuCashXml()

convert_to_target()

Convert the Ledger Book to a GnuCash V2 structure.

Source code in nomina/gnc_ledger.py
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
def convert_to_target(self) -> GncV2:
    """Convert the Ledger Book to a GnuCash V2 structure."""
    self.account_map: Dict[str, Account] = {}

    # Create GnuCash accounts
    gnc_accounts = [
        self.create_gnucash_account(account)
        for account in self.lbook.accounts.values()
    ]

    # Create GnuCash transactions
    gnc_transactions = [
        self.create_gnucash_transaction(transaction)
        for transaction in self.lbook.transactions.values()
    ]

    # Create GnuCash Book
    book = Book(
        id=Id(type_value="guid", value=self.generate_guid()),
        commodities=[
            Commodity(space="CURRENCY", id="EUR")
        ],  # Assuming EUR as default
        accounts=gnc_accounts,
        transactions=gnc_transactions,
        version="2.0.0",
    )
    book.update_count_data()

    # Create GncV2
    gnc_v2 = GncV2(count_data=CountData(type_value="book", value=1), book=book)
    self.target = gnc_v2
    return gnc_v2

create_gnucash_account(laccount)

Create a GnuCash account from a Ledger account.

Source code in nomina/gnc_ledger.py
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
def create_gnucash_account(self, laccount: LedgerAccount) -> Account:
    """Create a GnuCash account from a Ledger account."""
    gnc_account = Account(
        name=laccount.name,
        id=Id(type_value="guid", value=self.generate_guid()),
        type=laccount.account_type,
        commodity=Commodity(space="CURRENCY", id=laccount.currency),
        commodity_scu=100,
        parent=(
            Id(
                type_value="guid",
                value=self.account_map[laccount.parent_account_id].id.value,
            )
            if laccount.parent_account_id
            else None
        ),
        description=laccount.description,
        version="2.0.0",
    )
    self.account_map[laccount.account_id] = gnc_account
    return gnc_account

create_gnucash_split(lsplit, transaction_currency)

Create a GnuCash split from a Ledger split.

Source code in nomina/gnc_ledger.py
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def create_gnucash_split(
    self, lsplit: LedgerSplit, transaction_currency: str
) -> Split:
    """Create a GnuCash split from a Ledger split."""
    split = None
    if lsplit and lsplit.amount:
        if lsplit.account_id in self.account_map:
            account_id = self.account_map[lsplit.account_id].id.value
            split = Split(
                id=Id(type_value="guid", value=self.generate_guid()),
                memo=lsplit.memo,
                reconciled_state="n",
                value=f"{int(lsplit.amount * 100)}/100",
                quantity=f"{int(lsplit.amount * 100)}/100",
                account=Id(type_value="guid", value=account_id),
            )
        else:
            self.log.log(
                "❌", "split", f"unknown split account {lsplit.account_id}"
            )
    return split

create_gnucash_transaction(ltransaction)

Create a GnuCash transaction from a Ledger transaction.

Source code in nomina/gnc_ledger.py
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
def create_gnucash_transaction(
    self, ltransaction: LedgerTransaction
) -> Transaction:
    """Create a GnuCash transaction from a Ledger transaction."""
    currency = Commodity(space="CURRENCY", id="EUR")  # Assuming EUR as default
    gnc_splits = []
    for lsplit in ltransaction.splits:
        split = self.create_gnucash_split(lsplit, currency.id)
        if split:
            gnc_splits.append(split)

    return Transaction(
        id=Id(type_value="guid", value=self.generate_guid()),
        currency=currency,
        date_posted=TsDate(date=ltransaction.isodate),
        date_entered=TsDate(date=ltransaction.isodate),
        description=ltransaction.description,
        splits=gnc_splits,
        slots=Slots(
            slot=Slot(
                key="date-posted",
                value=Value(type_value="gdate", gdate=ltransaction.isodate),
            )
        ),
        version="2.0.0",
    )

generate_guid()

Generate a GUID for GnuCash entities.

Source code in nomina/gnc_ledger.py
166
167
168
def generate_guid(self) -> str:
    """Generate a GUID for GnuCash entities."""
    return uuid.uuid4().hex

load(input_path)

load the Ledger Book

Returns:

Name Type Description
LedgerBook Book

the ledger book

Source code in nomina/gnc_ledger.py
151
152
153
154
155
156
157
158
159
160
def load(self, input_path: str) -> LedgerBook:
    """
    load the Ledger Book

    Returns:
        LedgerBook: the ledger book
    """
    lbook = LedgerBook.load_from_yaml_file(input_path)
    self.set_source(lbook)
    return lbook

to_text()

convert to text

Source code in nomina/gnc_ledger.py
274
275
276
277
278
279
def to_text(self) -> str:
    """
    convert to text
    """
    xml_string = self.gcxml.to_text(self.target)
    return xml_string

gnucash

Created on 2024-10-02

@author: wf

GncV2 dataclass

Source code in nomina/gnucash.py
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
@dataclass
class GncV2:
    class Meta:
        name = "gnc-v2"
        namespace = None

    count_data: Optional[CountData] = field(
        default=None,
        metadata={
            "name": "count-data",
            "type": "Element",
            "namespace": "http://www.gnucash.org/XML/gnc",
            "required": True,
        },
    )
    book: Optional[Book] = field(
        default=None,
        metadata={
            "name": "book",
            "type": "Element",
            "namespace": "http://www.gnucash.org/XML/gnc",
        },
    )

    def get_stats(self) -> Stats:
        """
        Get statistics for the GncV2 object.
        """
        dates = []
        currency_usage = {}

        # Collect dates and currencies from transactions
        for transaction in self.book.transactions:
            if transaction.date_posted and transaction.date_posted.date:
                parsed_date = DateUtils.parse_date(transaction.date_posted.date)
                if parsed_date:
                    dates.append(parsed_date)

            if transaction.currency and transaction.currency.id:
                currency = transaction.currency.id
                if currency in currency_usage:
                    currency_usage[currency] += 1
                else:
                    currency_usage[currency] = 1

        # Determine the date range
        min_date = min(dates) if dates else None
        max_date = max(dates) if dates else None

        return Stats(
            accounts=len(self.book.accounts),
            transactions=len(self.book.transactions),
            start_date=min_date,
            end_date=max_date,
            currencies=currency_usage,
        )

get_stats()

Get statistics for the GncV2 object.

Source code in nomina/gnucash.py
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
def get_stats(self) -> Stats:
    """
    Get statistics for the GncV2 object.
    """
    dates = []
    currency_usage = {}

    # Collect dates and currencies from transactions
    for transaction in self.book.transactions:
        if transaction.date_posted and transaction.date_posted.date:
            parsed_date = DateUtils.parse_date(transaction.date_posted.date)
            if parsed_date:
                dates.append(parsed_date)

        if transaction.currency and transaction.currency.id:
            currency = transaction.currency.id
            if currency in currency_usage:
                currency_usage[currency] += 1
            else:
                currency_usage[currency] = 1

    # Determine the date range
    min_date = min(dates) if dates else None
    max_date = max(dates) if dates else None

    return Stats(
        accounts=len(self.book.accounts),
        transactions=len(self.book.transactions),
        start_date=min_date,
        end_date=max_date,
        currencies=currency_usage,
    )

GnuCashXml

GnuCash XML reader/writer

Source code in nomina/gnucash.py
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
class GnuCashXml:
    """
    GnuCash XML reader/writer
    """

    def __init__(self, indent: str = "  "):
        """
        constructor
        using two space indentation
        """
        self.indent = indent
        self.namespaces = {
            "gnc": "http://www.gnucash.org/XML/gnc",
            "act": "http://www.gnucash.org/XML/act",
            "book": "http://www.gnucash.org/XML/book",
            "cd": "http://www.gnucash.org/XML/cd",
            "cmdty": "http://www.gnucash.org/XML/cmdty",
            "price": "http://www.gnucash.org/XML/price",
            "slot": "http://www.gnucash.org/XML/slot",
            "split": "http://www.gnucash.org/XML/split",
            "sx": "http://www.gnucash.org/XML/sx",
            "trn": "http://www.gnucash.org/XML/trn",
            "ts": "http://www.gnucash.org/XML/ts",
            "fs": "http://www.gnucash.org/XML/fs",
            "bgt": "http://www.gnucash.org/XML/bgt",
            "recurrence": "http://www.gnucash.org/XML/recurrence",
            "lot": "http://www.gnucash.org/XML/lot",
            "addr": "http://www.gnucash.org/XML/addr",
            "billterm": "http://www.gnucash.org/XML/billterm",
            "bt-days": "http://www.gnucash.org/XML/bt-days",
            "bt-prox": "http://www.gnucash.org/XML/bt-prox",
            "cust": "http://www.gnucash.org/XML/cust",
            "employee": "http://www.gnucash.org/XML/employee",
            "entry": "http://www.gnucash.org/XML/entry",
            "invoice": "http://www.gnucash.org/XML/invoice",
            "job": "http://www.gnucash.org/XML/job",
            "order": "http://www.gnucash.org/XML/order",
            "owner": "http://www.gnucash.org/XML/owner",
            "taxtable": "http://www.gnucash.org/XML/taxtable",
            "tte": "http://www.gnucash.org/XML/tte",
            "vendor": "http://www.gnucash.org/XML/vendor",
        }

    def parse_gnucash_xml(self, xml_file: str) -> GncV2:
        """
        parse the given gnucash xml file - plain or gzipped as GnuCash saves by default, see issue #31
        """
        parser = XmlParser(config=ParserConfig(fail_on_unknown_properties=False))
        with open(xml_file, "rb") as f:
            xml_bytes = f.read()
        if xml_bytes[:2] == GZIP_MAGIC:
            xml_bytes = gzip.decompress(xml_bytes)
        gnc_v2 = parser.from_bytes(xml_bytes, GncV2)
        return gnc_v2

    def xml_format(self, xml_string: str) -> str:
        """
        adapt the format of the xml_string to gnu cash conventions
        """
        # unindent two spaces twice
        formatted_xml = re.sub(r"(\n  )", r"\n", xml_string)
        formatted_xml = re.sub(r"(\n  )", r"\n", formatted_xml)

        # formatting of xmlns attributes
        xmlns_indent = "     "  # Five spaces
        formatted_xml = re.sub(
            r'\s(xmlns:[^=]+="[^"]+")', f"\n{xmlns_indent}\\1", formatted_xml
        )

        # Ensure there's a space before the closing ?> in the XML declaration
        formatted_xml = formatted_xml.replace("?>", " ?>")

        # Consistent empty element formatting
        formatted_xml = re.sub(r"<([^>]+)\/>", r"<\1/>", formatted_xml)

        # add a new line at end
        formatted_xml += "\n"

        return formatted_xml

    def to_text(self, gnucash_data: GncV2) -> str:
        """
        Serialize the GnuCash data object to an XML string.

        Args:
            gnucash_data (GncV2): The GnuCash data object to serialize.

        Returns:
            str: The serialized XML string.
        """
        serializer = XmlSerializer(
            config=SerializerConfig(
                xml_declaration=True,
                encoding="utf-8",
                indent=self.indent,
            )
        )

        with io.StringIO() as xml_buffer:
            serializer.write(xml_buffer, gnucash_data, ns_map=self.namespaces)
            xml_string = xml_buffer.getvalue()

        # Apply the custom filter to the XML string
        formatted_xml_string = self.xml_format(xml_string)

        return formatted_xml_string

    def write_gnucash_xml(self, gnucash_data: GncV2, output_file: str) -> None:
        """
        Serialize the GnuCash data object to an XML file.

        Args:
            gnucash_data (GnuCashXml): The GnuCash data object to serialize.
            output_file (str): The file path where the XML will be written.
        """
        xml_string = self.to_text(gnucash_data)

        # Write the formatted XML string to the file
        with open(output_file, "w", encoding="UTF-8") as f:
            f.write(xml_string)

__init__(indent=' ')

constructor using two space indentation

Source code in nomina/gnucash.py
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
def __init__(self, indent: str = "  "):
    """
    constructor
    using two space indentation
    """
    self.indent = indent
    self.namespaces = {
        "gnc": "http://www.gnucash.org/XML/gnc",
        "act": "http://www.gnucash.org/XML/act",
        "book": "http://www.gnucash.org/XML/book",
        "cd": "http://www.gnucash.org/XML/cd",
        "cmdty": "http://www.gnucash.org/XML/cmdty",
        "price": "http://www.gnucash.org/XML/price",
        "slot": "http://www.gnucash.org/XML/slot",
        "split": "http://www.gnucash.org/XML/split",
        "sx": "http://www.gnucash.org/XML/sx",
        "trn": "http://www.gnucash.org/XML/trn",
        "ts": "http://www.gnucash.org/XML/ts",
        "fs": "http://www.gnucash.org/XML/fs",
        "bgt": "http://www.gnucash.org/XML/bgt",
        "recurrence": "http://www.gnucash.org/XML/recurrence",
        "lot": "http://www.gnucash.org/XML/lot",
        "addr": "http://www.gnucash.org/XML/addr",
        "billterm": "http://www.gnucash.org/XML/billterm",
        "bt-days": "http://www.gnucash.org/XML/bt-days",
        "bt-prox": "http://www.gnucash.org/XML/bt-prox",
        "cust": "http://www.gnucash.org/XML/cust",
        "employee": "http://www.gnucash.org/XML/employee",
        "entry": "http://www.gnucash.org/XML/entry",
        "invoice": "http://www.gnucash.org/XML/invoice",
        "job": "http://www.gnucash.org/XML/job",
        "order": "http://www.gnucash.org/XML/order",
        "owner": "http://www.gnucash.org/XML/owner",
        "taxtable": "http://www.gnucash.org/XML/taxtable",
        "tte": "http://www.gnucash.org/XML/tte",
        "vendor": "http://www.gnucash.org/XML/vendor",
    }

parse_gnucash_xml(xml_file)

parse the given gnucash xml file - plain or gzipped as GnuCash saves by default, see issue #31

Source code in nomina/gnucash.py
479
480
481
482
483
484
485
486
487
488
489
def parse_gnucash_xml(self, xml_file: str) -> GncV2:
    """
    parse the given gnucash xml file - plain or gzipped as GnuCash saves by default, see issue #31
    """
    parser = XmlParser(config=ParserConfig(fail_on_unknown_properties=False))
    with open(xml_file, "rb") as f:
        xml_bytes = f.read()
    if xml_bytes[:2] == GZIP_MAGIC:
        xml_bytes = gzip.decompress(xml_bytes)
    gnc_v2 = parser.from_bytes(xml_bytes, GncV2)
    return gnc_v2

to_text(gnucash_data)

Serialize the GnuCash data object to an XML string.

Parameters:

Name Type Description Default
gnucash_data GncV2

The GnuCash data object to serialize.

required

Returns:

Name Type Description
str str

The serialized XML string.

Source code in nomina/gnucash.py
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
def to_text(self, gnucash_data: GncV2) -> str:
    """
    Serialize the GnuCash data object to an XML string.

    Args:
        gnucash_data (GncV2): The GnuCash data object to serialize.

    Returns:
        str: The serialized XML string.
    """
    serializer = XmlSerializer(
        config=SerializerConfig(
            xml_declaration=True,
            encoding="utf-8",
            indent=self.indent,
        )
    )

    with io.StringIO() as xml_buffer:
        serializer.write(xml_buffer, gnucash_data, ns_map=self.namespaces)
        xml_string = xml_buffer.getvalue()

    # Apply the custom filter to the XML string
    formatted_xml_string = self.xml_format(xml_string)

    return formatted_xml_string

write_gnucash_xml(gnucash_data, output_file)

Serialize the GnuCash data object to an XML file.

Parameters:

Name Type Description Default
gnucash_data GnuCashXml

The GnuCash data object to serialize.

required
output_file str

The file path where the XML will be written.

required
Source code in nomina/gnucash.py
543
544
545
546
547
548
549
550
551
552
553
554
555
def write_gnucash_xml(self, gnucash_data: GncV2, output_file: str) -> None:
    """
    Serialize the GnuCash data object to an XML file.

    Args:
        gnucash_data (GnuCashXml): The GnuCash data object to serialize.
        output_file (str): The file path where the XML will be written.
    """
    xml_string = self.to_text(gnucash_data)

    # Write the formatted XML string to the file
    with open(output_file, "w", encoding="UTF-8") as f:
        f.write(xml_string)

xml_format(xml_string)

adapt the format of the xml_string to gnu cash conventions

Source code in nomina/gnucash.py
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
def xml_format(self, xml_string: str) -> str:
    """
    adapt the format of the xml_string to gnu cash conventions
    """
    # unindent two spaces twice
    formatted_xml = re.sub(r"(\n  )", r"\n", xml_string)
    formatted_xml = re.sub(r"(\n  )", r"\n", formatted_xml)

    # formatting of xmlns attributes
    xmlns_indent = "     "  # Five spaces
    formatted_xml = re.sub(
        r'\s(xmlns:[^=]+="[^"]+")', f"\n{xmlns_indent}\\1", formatted_xml
    )

    # Ensure there's a space before the closing ?> in the XML declaration
    formatted_xml = formatted_xml.replace("?>", " ?>")

    # Consistent empty element formatting
    formatted_xml = re.sub(r"<([^>]+)\/>", r"<\1/>", formatted_xml)

    # add a new line at end
    formatted_xml += "\n"

    return formatted_xml

TsDate dataclass

Source code in nomina/gnucash.py
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
@dataclass
class TsDate:
    date: Optional[str] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "http://www.gnucash.org/XML/ts",
        },
    )

    def __post_init__(self):
        """
        format date to 1970-01-01 00:00:00 +0000
        """
        if self.date and len(self.date) == 10:
            self.date += " 00:00:00 +0000"

__post_init__()

format date to 1970-01-01 00:00:00 +0000

Source code in nomina/gnucash.py
69
70
71
72
73
74
def __post_init__(self):
    """
    format date to 1970-01-01 00:00:00 +0000
    """
    if self.date and len(self.date) == 10:
        self.date += " 00:00:00 +0000"

ledger

Created on 04.10.2024

@author: wf

Account

Represents a ledger account.

Source code in nomina/ledger.py
19
20
21
22
23
24
25
26
27
28
29
30
@lod_storable
class Account:
    """
    Represents a ledger account.
    """

    account_id: str
    name: str
    account_type: str  # e.g. beancount compatible "Assets", "Liabilities", "Equity", "Income", "Expenses"
    description: Optional[str] = ""
    currency: str = "EUR"  # Default to EUR
    parent_account_id: Optional[str] = None

Book

Represents a ledger book containing accounts and transactions.

Source code in nomina/ledger.py
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
@lod_storable
class Book:
    """
    Represents a ledger book containing accounts and transactions.
    """

    file_type: str = "NOMINA-LEDGER-BOOK-YAML"
    version: str = "0.1"
    lenient = bool = False
    name: Optional[str] = None
    owner: Optional[str] = None
    since: Optional[str] = None
    url: Optional[str] = None
    accounts: Dict[str, Account] = field(default_factory=dict)
    transactions: Dict[str, Transaction] = field(default_factory=dict)

    def __post_init__(self):
        """
        post construct actions
        """
        self.log = Log()

    def fq_account_name(self, account: Account, separator: str = ":") -> str:
        """
        Returns the fully qualified name of the account, using the specified separator.

        Args:
            account (Account): The account for which to generate the fully qualified name.
            separator (str): The separator to use between parent and child account names. Defaults to ':'.

        Returns:
            str: The fully qualified name of the account.
        """
        if account.parent_account_id:
            parent_account = self.lookup_account(account.parent_account_id)
            if parent_account:
                parent_account_name = self.fq_account_name(parent_account, separator)
                return f"{parent_account_name}{separator}{account.name}"
        return account.name

    def get_stats(self) -> Stats:
        """
        Get statistics about the Book.

        Returns:
            Stats: An object containing various statistics about the Book.
        """
        # Calculate date range
        dates = [
            datetime.strptime(tx.isodate.split()[0], "%Y-%m-%d")
            for tx in self.transactions.values()
            if tx.isodate
        ]
        if dates:
            min_date = DateUtils.iso_date(min(dates))
            max_date = DateUtils.iso_date(max(dates))
        else:
            min_date = max_date = None

        # Calculate currency counts
        currency_counts = {}
        for account in self.accounts.values():
            currency = account.currency
            currency_counts[currency] = currency_counts.get(currency, 0) + 1

        return Stats(
            accounts=len(self.accounts),
            transactions=len(self.transactions),
            start_date=min_date,
            end_date=max_date,
            currencies=currency_counts,
        )

    def filter(
        self,
        start_date: str = None,
        end_date: str = None,
        remove_unused_accounts: bool = True,
    ) -> "Book":
        """
        Filter the transactions based on the given date range.

        Args:
            start_date (str): The start date in 'YYYY-MM-DD' format.
            end_date (str): The end date in 'YYYY-MM-DD' format.

        Returns:
            Book: A new Book object with filtered transactions.
        """
        filtered_transactions = {}

        for transaction_id, transaction in self.transactions.items():
            if transaction.isodate is not None:
                transaction_date = transaction.isodate.split()[
                    0
                ]  # Extract 'YYYY-MM-DD' part

                in_range = (not start_date or transaction_date >= start_date) and (
                    not end_date or transaction_date <= end_date
                )

                if in_range:
                    filtered_transactions[transaction_id] = transaction

        filtered_book = deepcopy(self)
        filtered_book.transactions = filtered_transactions
        if remove_unused_accounts:
            filtered_book.remove_unused_accounts()
        return filtered_book

    def create_account(
        self,
        name: str,
        description: str,
        account_type: str = "EXPENSE",
        parent_account_id: Optional[str] = None,
    ) -> Account:
        """
        Create a ledger account with the given parameters.

        Args:
            name (str): The name of the account.
            description(str): the description of the account
            account_type (str): The type of the account. Defaults to "EXPENSE".
            parent_account_id (Optional[str]): The id of the parent account, if any.

        Returns:
            Account: A new Account object.
        """
        # Calculate the account ID based on the parent's account ID (if any)
        if parent_account_id:
            parent_account = self.lookup_account(parent_account_id)
            if parent_account:
                account_id = f"{parent_account_id}:{name}"
            else:
                raise ValueError(f"invalid parent account {parent_account_id}")
        else:
            account_id = name  # top level account

        # Create the account
        account = Account(
            account_id=account_id,
            name=name,
            description=description,
            account_type=account_type,
            parent_account_id=parent_account_id,
        )
        self.add_account(account)

    def add_account(self, account: Account):
        """
        add the given account
        """
        self.accounts[account.account_id] = account
        return account

    def lookup_account(self, account_id: str) -> Optional[Account]:
        """
        Get the account for the given account id.

        Args:
            account_id(str): The id of the account to look up.

        Returns:
            Optional[Account]: The found account or None if not found.
        """
        return self.accounts.get(account_id)

    def calc_balances(self) -> Dict[str, Optional[float]]:
        """
        Calculate the balances for all accounts, including propagation up the account hierarchy.
        Unused accounts will have a balance of None.

        Returns:
            Dict[str, Optional[float]]: A dictionary mapping account IDs to their balances or None if unused.
        """
        balances = {account_id: None for account_id in self.accounts}

        # First pass: Calculate balances from transactions
        for ti, transaction in enumerate(self.transactions.values(), start=1):
            for si, split in enumerate(transaction.splits, start=1):
                if not split or not split.amount:
                    msg = f"split {si} (or amount) of transaction {ti} is None"
                    if self.lenient:
                        self.log.log("⚠️", "split", msg)
                    else:
                        raise ValueError(msg)
                    continue
                else:
                    if balances[split.account_id] is None:
                        balances[split.account_id] = split.amount
                    else:
                        balances[split.account_id] += split.amount

        # Second pass: Propagate balances up the hierarchy
        for account in self.accounts.values():
            if account.parent_account_id:
                child_balance = balances[account.account_id]
                if child_balance is not None:
                    if balances[account.parent_account_id] is None:
                        balances[account.parent_account_id] = child_balance
                    else:
                        balances[account.parent_account_id] += child_balance

        return balances

    def remove_unused_accounts(self) -> None:
        """
        Remove accounts that have not been used in any transactions.
        """
        balances = self.calc_balances()

        # Remove accounts that have not been used (balance is None)
        accounts_to_remove = [
            account_id for account_id, balance in balances.items() if balance is None
        ]
        for account_id in accounts_to_remove:
            del self.accounts[account_id]

__post_init__()

post construct actions

Source code in nomina/ledger.py
83
84
85
86
87
def __post_init__(self):
    """
    post construct actions
    """
    self.log = Log()

add_account(account)

add the given account

Source code in nomina/ledger.py
216
217
218
219
220
221
def add_account(self, account: Account):
    """
    add the given account
    """
    self.accounts[account.account_id] = account
    return account

calc_balances()

Calculate the balances for all accounts, including propagation up the account hierarchy. Unused accounts will have a balance of None.

Returns:

Type Description
Dict[str, Optional[float]]

Dict[str, Optional[float]]: A dictionary mapping account IDs to their balances or None if unused.

Source code in nomina/ledger.py
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
def calc_balances(self) -> Dict[str, Optional[float]]:
    """
    Calculate the balances for all accounts, including propagation up the account hierarchy.
    Unused accounts will have a balance of None.

    Returns:
        Dict[str, Optional[float]]: A dictionary mapping account IDs to their balances or None if unused.
    """
    balances = {account_id: None for account_id in self.accounts}

    # First pass: Calculate balances from transactions
    for ti, transaction in enumerate(self.transactions.values(), start=1):
        for si, split in enumerate(transaction.splits, start=1):
            if not split or not split.amount:
                msg = f"split {si} (or amount) of transaction {ti} is None"
                if self.lenient:
                    self.log.log("⚠️", "split", msg)
                else:
                    raise ValueError(msg)
                continue
            else:
                if balances[split.account_id] is None:
                    balances[split.account_id] = split.amount
                else:
                    balances[split.account_id] += split.amount

    # Second pass: Propagate balances up the hierarchy
    for account in self.accounts.values():
        if account.parent_account_id:
            child_balance = balances[account.account_id]
            if child_balance is not None:
                if balances[account.parent_account_id] is None:
                    balances[account.parent_account_id] = child_balance
                else:
                    balances[account.parent_account_id] += child_balance

    return balances

create_account(name, description, account_type='EXPENSE', parent_account_id=None)

Create a ledger account with the given parameters.

Parameters:

Name Type Description Default
name str

The name of the account.

required
description(str)

the description of the account

required
account_type str

The type of the account. Defaults to "EXPENSE".

'EXPENSE'
parent_account_id Optional[str]

The id of the parent account, if any.

None

Returns:

Name Type Description
Account Account

A new Account object.

Source code in nomina/ledger.py
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def create_account(
    self,
    name: str,
    description: str,
    account_type: str = "EXPENSE",
    parent_account_id: Optional[str] = None,
) -> Account:
    """
    Create a ledger account with the given parameters.

    Args:
        name (str): The name of the account.
        description(str): the description of the account
        account_type (str): The type of the account. Defaults to "EXPENSE".
        parent_account_id (Optional[str]): The id of the parent account, if any.

    Returns:
        Account: A new Account object.
    """
    # Calculate the account ID based on the parent's account ID (if any)
    if parent_account_id:
        parent_account = self.lookup_account(parent_account_id)
        if parent_account:
            account_id = f"{parent_account_id}:{name}"
        else:
            raise ValueError(f"invalid parent account {parent_account_id}")
    else:
        account_id = name  # top level account

    # Create the account
    account = Account(
        account_id=account_id,
        name=name,
        description=description,
        account_type=account_type,
        parent_account_id=parent_account_id,
    )
    self.add_account(account)

filter(start_date=None, end_date=None, remove_unused_accounts=True)

Filter the transactions based on the given date range.

Parameters:

Name Type Description Default
start_date str

The start date in 'YYYY-MM-DD' format.

None
end_date str

The end date in 'YYYY-MM-DD' format.

None

Returns:

Name Type Description
Book Book

A new Book object with filtered transactions.

Source code in nomina/ledger.py
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def filter(
    self,
    start_date: str = None,
    end_date: str = None,
    remove_unused_accounts: bool = True,
) -> "Book":
    """
    Filter the transactions based on the given date range.

    Args:
        start_date (str): The start date in 'YYYY-MM-DD' format.
        end_date (str): The end date in 'YYYY-MM-DD' format.

    Returns:
        Book: A new Book object with filtered transactions.
    """
    filtered_transactions = {}

    for transaction_id, transaction in self.transactions.items():
        if transaction.isodate is not None:
            transaction_date = transaction.isodate.split()[
                0
            ]  # Extract 'YYYY-MM-DD' part

            in_range = (not start_date or transaction_date >= start_date) and (
                not end_date or transaction_date <= end_date
            )

            if in_range:
                filtered_transactions[transaction_id] = transaction

    filtered_book = deepcopy(self)
    filtered_book.transactions = filtered_transactions
    if remove_unused_accounts:
        filtered_book.remove_unused_accounts()
    return filtered_book

fq_account_name(account, separator=':')

Returns the fully qualified name of the account, using the specified separator.

Parameters:

Name Type Description Default
account Account

The account for which to generate the fully qualified name.

required
separator str

The separator to use between parent and child account names. Defaults to ':'.

':'

Returns:

Name Type Description
str str

The fully qualified name of the account.

Source code in nomina/ledger.py
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def fq_account_name(self, account: Account, separator: str = ":") -> str:
    """
    Returns the fully qualified name of the account, using the specified separator.

    Args:
        account (Account): The account for which to generate the fully qualified name.
        separator (str): The separator to use between parent and child account names. Defaults to ':'.

    Returns:
        str: The fully qualified name of the account.
    """
    if account.parent_account_id:
        parent_account = self.lookup_account(account.parent_account_id)
        if parent_account:
            parent_account_name = self.fq_account_name(parent_account, separator)
            return f"{parent_account_name}{separator}{account.name}"
    return account.name

get_stats()

Get statistics about the Book.

Returns:

Name Type Description
Stats Stats

An object containing various statistics about the Book.

Source code in nomina/ledger.py
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
def get_stats(self) -> Stats:
    """
    Get statistics about the Book.

    Returns:
        Stats: An object containing various statistics about the Book.
    """
    # Calculate date range
    dates = [
        datetime.strptime(tx.isodate.split()[0], "%Y-%m-%d")
        for tx in self.transactions.values()
        if tx.isodate
    ]
    if dates:
        min_date = DateUtils.iso_date(min(dates))
        max_date = DateUtils.iso_date(max(dates))
    else:
        min_date = max_date = None

    # Calculate currency counts
    currency_counts = {}
    for account in self.accounts.values():
        currency = account.currency
        currency_counts[currency] = currency_counts.get(currency, 0) + 1

    return Stats(
        accounts=len(self.accounts),
        transactions=len(self.transactions),
        start_date=min_date,
        end_date=max_date,
        currencies=currency_counts,
    )

lookup_account(account_id)

Get the account for the given account id.

Parameters:

Name Type Description Default
account_id(str)

The id of the account to look up.

required

Returns:

Type Description
Optional[Account]

Optional[Account]: The found account or None if not found.

Source code in nomina/ledger.py
223
224
225
226
227
228
229
230
231
232
233
def lookup_account(self, account_id: str) -> Optional[Account]:
    """
    Get the account for the given account id.

    Args:
        account_id(str): The id of the account to look up.

    Returns:
        Optional[Account]: The found account or None if not found.
    """
    return self.accounts.get(account_id)

remove_unused_accounts()

Remove accounts that have not been used in any transactions.

Source code in nomina/ledger.py
273
274
275
276
277
278
279
280
281
282
283
284
def remove_unused_accounts(self) -> None:
    """
    Remove accounts that have not been used in any transactions.
    """
    balances = self.calc_balances()

    # Remove accounts that have not been used (balance is None)
    accounts_to_remove = [
        account_id for account_id, balance in balances.items() if balance is None
    ]
    for account_id in accounts_to_remove:
        del self.accounts[account_id]

Split

Represents a split in a transaction.

Source code in nomina/ledger.py
33
34
35
36
37
38
39
40
41
42
43
@lod_storable
class Split:
    """
    Represents a split in a transaction.
    """

    amount: float
    account_id: str
    memo: Optional[str] = ""
    reconciled: bool = False
    vat_code: Optional[str] = None  # e.g. N1_O see nomina.vat_codes

Transaction

Represents a transaction in the ledger.

Source code in nomina/ledger.py
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
@lod_storable
class Transaction:
    """
    Represents a transaction in the ledger.
    """

    isodate: str = None
    description: Optional[str] = None
    splits: List[Split] = field(default_factory=list)
    payee: Optional[str] = None
    memo: Optional[str] = ""

    def total_amount(self) -> float:
        """
        Calculates the total amount of the transaction.
        Returns:
            float: The sum of all split amounts.
        """
        return sum(split.amount for split in self.splits)

total_amount()

Calculates the total amount of the transaction. Returns: float: The sum of all split amounts.

Source code in nomina/ledger.py
58
59
60
61
62
63
64
def total_amount(self) -> float:
    """
    Calculates the total amount of the transaction.
    Returns:
        float: The sum of all split amounts.
    """
    return sum(split.amount for split in self.splits)

money_zip

Created on 2024-10-14

@author: wf

MnyToZipConverter

Convert Microsoft Money Files to ZIP file with JSON dumps of all tables and a header YAML file

Source code in nomina/money_zip.py
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
class MnyToZipConverter:
    """
    Convert Microsoft Money Files to ZIP file with JSON dumps of all tables
    and a header YAML file
    """

    # Color definitions
    BLUE = "\033[0;34m"
    RED = "\033[0;31m"
    GREEN = "\033[0;32m"
    END_COLOR = "\033[0m"

    # Default values
    VERSION = "0.0.2"

    def __init__(self):
        self.debug = False
        self.verbose = False
        self.keep_temp = False
        self.output_dir = None

    def color_msg(self, color, msg):
        """Display colored messages with UTF-8 symbols."""
        print(f"{color}{msg}{self.END_COLOR}")

    def error(self, msg):
        """Display errors and exit."""
        self.color_msg(self.RED, f"✖ {msg}")
        sys.exit(1)

    def positive(self, msg):
        """Display positive messages."""
        self.color_msg(self.GREEN, f"✔ {msg}")

    def negative(self, msg):
        """Display negative messages."""
        self.color_msg(self.RED, f"✖ {msg}")

    def check_tools(self):
        """Check if required tools are available."""
        tools = ["mdb-ver", "mdb-tables", "mdb-json"]
        ok = True
        for tool in tools:
            if shutil.which(tool):
                self.positive(f"{tool} is available")
            else:
                self.negative(f"{tool} is not installed or not found in PATH")
                ok = False
        if not ok:
            self.negative(
                "You might want to install https://github.com/mdbtools/mdbtools on your system"
            )

    def create_yaml_declaration(self, mny_file, yaml_file):
        """Create YAML declaration file."""
        try:
            mdb_ver = subprocess.check_output(
                ["mdb-ver", mny_file], universal_newlines=True
            ).strip()
            file_date = datetime.fromtimestamp(os.path.getmtime(mny_file)).isoformat()
            file_size = os.path.getsize(mny_file)

            with open(mny_file, "rb") as f:
                file_hash = hashlib.sha256(f.read()).hexdigest()

            yaml_data = {
                "file_type": "NOMINA-MICROSOFT-MONEY-YAML",
                "version": "0.1",
                "name": mny_file,
                "date": file_date,
                "size": file_size,
                "sha256": file_hash,
                "jetversion": mdb_ver,
            }

            self.color_msg(self.BLUE, f"{yaml_file} ...")
            with open(yaml_file, "w") as f:
                yaml.dump(yaml_data, f)

        except subprocess.CalledProcessError:
            self.error("YAML creation failed")

    def export_tables_to_json(self, mny_file, output_dir):
        """Export tables of the given Microsoft Money file to JSON files."""
        tables = subprocess.check_output(
            ["mdb-tables", "-1", mny_file], universal_newlines=True
        ).split()

        for table in tables:
            json_file = os.path.join(output_dir, f"{table}.json")
            self.color_msg(self.BLUE, f"{table} ...")
            msg = f"{table} → {json_file}"

            try:
                with open(json_file, "w") as f:
                    subprocess.run(["mdb-json", mny_file, table], stdout=f, check=True)

                if os.path.getsize(json_file) > 0:
                    self.positive(msg)
                else:
                    raise subprocess.CalledProcessError(1, "mdb-json")

            except subprocess.CalledProcessError:
                self.negative(msg)
                if os.path.exists(json_file):
                    os.remove(json_file)

    def export_mny_to_zip(self, mny_file) -> str:
        """Export the given money file to a zip file that pynomina might be able to read."""
        basename = os.path.splitext(os.path.basename(mny_file))[0]
        if self.output_dir is None:
            self.output_dir = f"/tmp/{basename}_mdb_dump"
        zip_file = f"{basename}.zip"
        yaml_file = os.path.join(self.output_dir, "nomina.yaml")

        try:
            os.makedirs(self.output_dir, exist_ok=True)
            self.create_yaml_declaration(mny_file, yaml_file)
            self.export_tables_to_json(mny_file, self.output_dir)

            self.color_msg(self.BLUE, "→ Creating zip archive...")
            shutil.make_archive(basename, "zip", self.output_dir)

            if not self.keep_temp:
                shutil.rmtree(self.output_dir)
            else:
                self.positive(f"Temporary files kept in {self.output_dir}")

            self.positive(f"Conversion complete. Output file: {zip_file}")

        except Exception as e:
            self.error(f"Failed to create zip archive: {str(e)}")
        return zip_file

    def run(self):
        parser = argparse.ArgumentParser(
            description="Convert Microsoft Money files to ZIP"
        )
        parser.add_argument(
            "-ct",
            "--checktools",
            action="store_true",
            help="Check if required tools are installed",
        )
        parser.add_argument(
            "-d", "--debug", action="store_true", help="Enable debug output"
        )
        parser.add_argument(
            "--keep",
            action="store_true",
            help="Keep the temporary files after conversion",
        )
        parser.add_argument(
            "--version", action="version", version=f"Version: {self.VERSION}"
        )
        parser.add_argument(
            "-o",
            "--output",
            help="Specify the output directory - default: /tmp/[basename]_money_dump",
        )
        parser.add_argument(
            "mny_file", nargs="?", help="Microsoft Money file to convert"
        )

        args = parser.parse_args()

        self.debug = args.debug
        self.keep_temp = args.keep
        self.output_dir = args.output

        if args.checktools:
            self.check_tools()
        elif args.mny_file:
            if not args.mny_file.endswith(".mny"):
                self.error("Input file must have .mny extension")
            self.export_mny_to_zip(args.mny_file)
        else:
            parser.print_help()

check_tools()

Check if required tools are available.

Source code in nomina/money_zip.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def check_tools(self):
    """Check if required tools are available."""
    tools = ["mdb-ver", "mdb-tables", "mdb-json"]
    ok = True
    for tool in tools:
        if shutil.which(tool):
            self.positive(f"{tool} is available")
        else:
            self.negative(f"{tool} is not installed or not found in PATH")
            ok = False
    if not ok:
        self.negative(
            "You might want to install https://github.com/mdbtools/mdbtools on your system"
        )

color_msg(color, msg)

Display colored messages with UTF-8 symbols.

Source code in nomina/money_zip.py
39
40
41
def color_msg(self, color, msg):
    """Display colored messages with UTF-8 symbols."""
    print(f"{color}{msg}{self.END_COLOR}")

create_yaml_declaration(mny_file, yaml_file)

Create YAML declaration file.

Source code in nomina/money_zip.py
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
def create_yaml_declaration(self, mny_file, yaml_file):
    """Create YAML declaration file."""
    try:
        mdb_ver = subprocess.check_output(
            ["mdb-ver", mny_file], universal_newlines=True
        ).strip()
        file_date = datetime.fromtimestamp(os.path.getmtime(mny_file)).isoformat()
        file_size = os.path.getsize(mny_file)

        with open(mny_file, "rb") as f:
            file_hash = hashlib.sha256(f.read()).hexdigest()

        yaml_data = {
            "file_type": "NOMINA-MICROSOFT-MONEY-YAML",
            "version": "0.1",
            "name": mny_file,
            "date": file_date,
            "size": file_size,
            "sha256": file_hash,
            "jetversion": mdb_ver,
        }

        self.color_msg(self.BLUE, f"{yaml_file} ...")
        with open(yaml_file, "w") as f:
            yaml.dump(yaml_data, f)

    except subprocess.CalledProcessError:
        self.error("YAML creation failed")

error(msg)

Display errors and exit.

Source code in nomina/money_zip.py
43
44
45
46
def error(self, msg):
    """Display errors and exit."""
    self.color_msg(self.RED, f"✖ {msg}")
    sys.exit(1)

export_mny_to_zip(mny_file)

Export the given money file to a zip file that pynomina might be able to read.

Source code in nomina/money_zip.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
def export_mny_to_zip(self, mny_file) -> str:
    """Export the given money file to a zip file that pynomina might be able to read."""
    basename = os.path.splitext(os.path.basename(mny_file))[0]
    if self.output_dir is None:
        self.output_dir = f"/tmp/{basename}_mdb_dump"
    zip_file = f"{basename}.zip"
    yaml_file = os.path.join(self.output_dir, "nomina.yaml")

    try:
        os.makedirs(self.output_dir, exist_ok=True)
        self.create_yaml_declaration(mny_file, yaml_file)
        self.export_tables_to_json(mny_file, self.output_dir)

        self.color_msg(self.BLUE, "→ Creating zip archive...")
        shutil.make_archive(basename, "zip", self.output_dir)

        if not self.keep_temp:
            shutil.rmtree(self.output_dir)
        else:
            self.positive(f"Temporary files kept in {self.output_dir}")

        self.positive(f"Conversion complete. Output file: {zip_file}")

    except Exception as e:
        self.error(f"Failed to create zip archive: {str(e)}")
    return zip_file

export_tables_to_json(mny_file, output_dir)

Export tables of the given Microsoft Money file to JSON files.

Source code in nomina/money_zip.py
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def export_tables_to_json(self, mny_file, output_dir):
    """Export tables of the given Microsoft Money file to JSON files."""
    tables = subprocess.check_output(
        ["mdb-tables", "-1", mny_file], universal_newlines=True
    ).split()

    for table in tables:
        json_file = os.path.join(output_dir, f"{table}.json")
        self.color_msg(self.BLUE, f"{table} ...")
        msg = f"{table} → {json_file}"

        try:
            with open(json_file, "w") as f:
                subprocess.run(["mdb-json", mny_file, table], stdout=f, check=True)

            if os.path.getsize(json_file) > 0:
                self.positive(msg)
            else:
                raise subprocess.CalledProcessError(1, "mdb-json")

        except subprocess.CalledProcessError:
            self.negative(msg)
            if os.path.exists(json_file):
                os.remove(json_file)

negative(msg)

Display negative messages.

Source code in nomina/money_zip.py
52
53
54
def negative(self, msg):
    """Display negative messages."""
    self.color_msg(self.RED, f"✖ {msg}")

positive(msg)

Display positive messages.

Source code in nomina/money_zip.py
48
49
50
def positive(self, msg):
    """Display positive messages."""
    self.color_msg(self.GREEN, f"✔ {msg}")

msmoney

Created on 2024-10-09

@author: wf

MsMoney

Wrapper for Microsoft Money content

Source code in nomina/msmoney.py
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
class MsMoney:
    """
    Wrapper for Microsoft Money content
    """

    def __init__(self):
        self.header = None
        self.graph = MogwaiGraph()

    def load(self, path: str):
        """
        Load Microsoft Money data from a ZIP file or a directory
        """
        if os.path.isdir(path):
            file_generator = self._generate_files_from_directory(path)
        else:
            file_generator = self._generate_files_from_zip(path)

        self._handle_files(file_generator)

    def _generate_files_from_zip(self, zip_path: str):
        """
        Generator that yields file name and file object from a ZIP file
        """
        with ZipFile(zip_path, "r") as zip_file:
            for file_name in zip_file.namelist():
                with zip_file.open(file_name) as file_content:
                    yield file_name, file_content

    def _generate_files_from_directory(self, dir_path: str):
        """
        Generator that yields file name and file object from a directory
        """
        for file_name in os.listdir(dir_path):
            file_path = os.path.join(dir_path, file_name)
            with open(file_path, "r") as file_content:
                yield file_name, file_content

    def _handle_files(self, file_generator):
        """
        Handle the files yielded by the generator (from ZIP or directory)
        """
        for file_name, file_content in file_generator:
            if file_name == "nomina.yaml":
                # Load the YAML file
                self.header = ZipHeader.load_from_yaml_stream(file_content)
            elif file_name.endswith(".json"):
                try:
                    # Load JSON files as networkx nodes
                    self.add_nodes_from_json(file_name, file_content)
                except json.JSONDecodeError as e:
                    print(f"Error decoding JSON in file {file_name}: {e}")
                    continue

    def add_nodes_from_json(self, file_name, file_content):
        """
        Add nodes from JSON data to the graph
        """
        table_name = file_name.split(".")[0]  # Remove the .json extension

        for line in file_content:
            line = line.strip()
            if line:  # Skip empty lines
                try:
                    json_data = json.loads(line)
                    self.add_node(table_name, json_data)
                except json.JSONDecodeError as e:
                    print(f"Error decoding JSON object in file {file_name}: {e}")

    def add_node(self, table_name, data):
        """
        Add a single node to the graph
        """
        node_id = data.get("id", str(len(self.graph)))
        self.graph.add_labeled_node(node_id, name=table_name, **data)

    def to_transaction_dict(self, data) -> Dict[str, Any]:
        """
        convert a data node to a transcaction dict with transaction_id and isodate
        """
        tx_dict = None
        if data.get("type") == "TRN":
            transaction_id = str(data.get("htrn"))
            t_date = data.get("dt")
            isodate = DateUtils.parse_date(t_date)
            tx_dict = {
                "transaction_id": transaction_id,
                "isodate": isodate,
                "amount": data.get("amt", 0.0),
                "account_id": data.get("hacct"),
            }
        return tx_dict

    def get_stats(self) -> Stats:
        """
        Get statistics about the Microsoft Money data.

        Returns:
            Stats: An object containing various statistics about the data.
        """
        nodes = self.graph.nodes(data=True)  # Assign for clarity

        # Calculate date range
        dates = []
        transactions = 0

        for _node, data in nodes:
            tx_dict = self.to_transaction_dict(data)
            if tx_dict is not None:
                transactions += 1
                dates.append(tx_dict["isodate"])

        if dates:
            min_date = min(dates)
            max_date = max(dates)
        else:
            min_date = max_date = None

        # Count accounts and calculate currency counts
        accounts = 0
        currency_counts = {}
        for _node, data in nodes:
            if data.get("type") == "ACCT":
                accounts += 1
                currency = data.get("currency", "UNKNOWN")
                currency_counts[currency] = currency_counts.get(currency, 0) + 1

        return Stats(
            accounts=accounts,
            transactions=transactions,
            start_date=min_date,
            end_date=max_date,
            currencies=currency_counts,
        )

add_node(table_name, data)

Add a single node to the graph

Source code in nomina/msmoney.py
 99
100
101
102
103
104
def add_node(self, table_name, data):
    """
    Add a single node to the graph
    """
    node_id = data.get("id", str(len(self.graph)))
    self.graph.add_labeled_node(node_id, name=table_name, **data)

add_nodes_from_json(file_name, file_content)

Add nodes from JSON data to the graph

Source code in nomina/msmoney.py
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def add_nodes_from_json(self, file_name, file_content):
    """
    Add nodes from JSON data to the graph
    """
    table_name = file_name.split(".")[0]  # Remove the .json extension

    for line in file_content:
        line = line.strip()
        if line:  # Skip empty lines
            try:
                json_data = json.loads(line)
                self.add_node(table_name, json_data)
            except json.JSONDecodeError as e:
                print(f"Error decoding JSON object in file {file_name}: {e}")

get_stats()

Get statistics about the Microsoft Money data.

Returns:

Name Type Description
Stats Stats

An object containing various statistics about the data.

Source code in nomina/msmoney.py
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def get_stats(self) -> Stats:
    """
    Get statistics about the Microsoft Money data.

    Returns:
        Stats: An object containing various statistics about the data.
    """
    nodes = self.graph.nodes(data=True)  # Assign for clarity

    # Calculate date range
    dates = []
    transactions = 0

    for _node, data in nodes:
        tx_dict = self.to_transaction_dict(data)
        if tx_dict is not None:
            transactions += 1
            dates.append(tx_dict["isodate"])

    if dates:
        min_date = min(dates)
        max_date = max(dates)
    else:
        min_date = max_date = None

    # Count accounts and calculate currency counts
    accounts = 0
    currency_counts = {}
    for _node, data in nodes:
        if data.get("type") == "ACCT":
            accounts += 1
            currency = data.get("currency", "UNKNOWN")
            currency_counts[currency] = currency_counts.get(currency, 0) + 1

    return Stats(
        accounts=accounts,
        transactions=transactions,
        start_date=min_date,
        end_date=max_date,
        currencies=currency_counts,
    )

load(path)

Load Microsoft Money data from a ZIP file or a directory

Source code in nomina/msmoney.py
39
40
41
42
43
44
45
46
47
48
def load(self, path: str):
    """
    Load Microsoft Money data from a ZIP file or a directory
    """
    if os.path.isdir(path):
        file_generator = self._generate_files_from_directory(path)
    else:
        file_generator = self._generate_files_from_zip(path)

    self._handle_files(file_generator)

to_transaction_dict(data)

convert a data node to a transcaction dict with transaction_id and isodate

Source code in nomina/msmoney.py
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def to_transaction_dict(self, data) -> Dict[str, Any]:
    """
    convert a data node to a transcaction dict with transaction_id and isodate
    """
    tx_dict = None
    if data.get("type") == "TRN":
        transaction_id = str(data.get("htrn"))
        t_date = data.get("dt")
        isodate = DateUtils.parse_date(t_date)
        tx_dict = {
            "transaction_id": transaction_id,
            "isodate": isodate,
            "amount": data.get("amt", 0.0),
            "account_id": data.get("hacct"),
        }
    return tx_dict

msmoney_ledger

Created on 09.10.2024

@author: wf

MicrosoftMoneyToLedgerConverter

Bases: BaseToLedgerConverter

Microsoft Money to Ledger Converter

Source code in nomina/msmoney_ledger.py
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
class MicrosoftMoneyToLedgerConverter(BaseToLedgerConverter):
    """
    Microsoft Money to Ledger Converter
    """

    def __init__(self, debug: bool = False):
        """
        Constructor for Microsoft Money to Ledger Book conversion.

        Args:
            debug (bool): Whether to enable debug logging.
        """
        super().__init__(from_format_acronym="MONEY", debug=debug)
        self.ms_money = None

    def load(self, input_path: Path) -> MsMoney:
        """
        Load Microsoft Money data
        """
        self.ms_money = MsMoney()
        self.ms_money.load(str(input_path))
        self.source = self.ms_money
        return self.source

    def convert_to_target(self) -> Book:
        """
        convert the microsoft money entries to a Ledger Book
        """
        book = Book()
        book.name = self.ms_money.header.name if self.ms_money.header else "Unknown"
        book.since = self.ms_money.header.date if self.ms_money.header else None
        nodes = self.ms_money.graph.nodes(data=True)
        self.log.log("✅", "graph", f"Total nodes: {len(nodes)}")
        node_types = set(data.get("type", "Unknown") for _, data in nodes)
        self.log.log("✅", "graph", f"Node types: {node_types}")

        # Create accounts
        for node, data in nodes:
            if data.get("type") == "ACCT":
                account = Account(
                    account_id=str(data.get("hacct")),
                    name=data.get("szFull", ""),
                    account_type=data.get("acct_type", "EXPENSE"),
                    description=data.get("desc", ""),
                    currency=data.get("currency", "EUR"),
                )
                book.add_account(account)

        self.log.log("✅", "accounts", f"Accounts created: {len(book.accounts)}")

        # Create transactions
        for _node, data in nodes:
            tx_dict = self.ms_money.to_transaction_dict(data)
            if tx_dict is not None:
                isodate = tx_dict["isodate"]
                amount = tx_dict["amount"]
                transaction_id = tx_dict["transaction_id"]
                account_id = tx_dict["account_id"]
                transaction = Transaction(
                    isodate=isodate,
                    description=f"Transaction {transaction_id}",  # No clear description field, using a placeholder
                    splits=[],  # We'll handle splits later
                    payee="",  # No clear payee field in the example
                    memo=f"Amount: {amount}",
                )

                # Add a single split for now, we'll refine this later
                split = Split(
                    amount=float(amount),
                    account_id=account_id,
                    memo=f"Transaction {transaction_id}",
                )
                transaction.splits.append(split)

                book.transactions[transaction_id] = transaction

        self.log.log(
            "✅", "transactions", f"Transactions created: {len(book.transactions)}"
        )

        self.target = book
        return book

    def to_text(self) -> str:
        yaml_str = self.target.to_yaml()
        return yaml_str

__init__(debug=False)

Constructor for Microsoft Money to Ledger Book conversion.

Parameters:

Name Type Description Default
debug bool

Whether to enable debug logging.

False
Source code in nomina/msmoney_ledger.py
19
20
21
22
23
24
25
26
27
def __init__(self, debug: bool = False):
    """
    Constructor for Microsoft Money to Ledger Book conversion.

    Args:
        debug (bool): Whether to enable debug logging.
    """
    super().__init__(from_format_acronym="MONEY", debug=debug)
    self.ms_money = None

convert_to_target()

convert the microsoft money entries to a Ledger Book

Source code in nomina/msmoney_ledger.py
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def convert_to_target(self) -> Book:
    """
    convert the microsoft money entries to a Ledger Book
    """
    book = Book()
    book.name = self.ms_money.header.name if self.ms_money.header else "Unknown"
    book.since = self.ms_money.header.date if self.ms_money.header else None
    nodes = self.ms_money.graph.nodes(data=True)
    self.log.log("✅", "graph", f"Total nodes: {len(nodes)}")
    node_types = set(data.get("type", "Unknown") for _, data in nodes)
    self.log.log("✅", "graph", f"Node types: {node_types}")

    # Create accounts
    for node, data in nodes:
        if data.get("type") == "ACCT":
            account = Account(
                account_id=str(data.get("hacct")),
                name=data.get("szFull", ""),
                account_type=data.get("acct_type", "EXPENSE"),
                description=data.get("desc", ""),
                currency=data.get("currency", "EUR"),
            )
            book.add_account(account)

    self.log.log("✅", "accounts", f"Accounts created: {len(book.accounts)}")

    # Create transactions
    for _node, data in nodes:
        tx_dict = self.ms_money.to_transaction_dict(data)
        if tx_dict is not None:
            isodate = tx_dict["isodate"]
            amount = tx_dict["amount"]
            transaction_id = tx_dict["transaction_id"]
            account_id = tx_dict["account_id"]
            transaction = Transaction(
                isodate=isodate,
                description=f"Transaction {transaction_id}",  # No clear description field, using a placeholder
                splits=[],  # We'll handle splits later
                payee="",  # No clear payee field in the example
                memo=f"Amount: {amount}",
            )

            # Add a single split for now, we'll refine this later
            split = Split(
                amount=float(amount),
                account_id=account_id,
                memo=f"Transaction {transaction_id}",
            )
            transaction.splits.append(split)

            book.transactions[transaction_id] = transaction

    self.log.log(
        "✅", "transactions", f"Transactions created: {len(book.transactions)}"
    )

    self.target = book
    return book

load(input_path)

Load Microsoft Money data

Source code in nomina/msmoney_ledger.py
29
30
31
32
33
34
35
36
def load(self, input_path: Path) -> MsMoney:
    """
    Load Microsoft Money data
    """
    self.ms_money = MsMoney()
    self.ms_money.load(str(input_path))
    self.source = self.ms_money
    return self.source

nomina_beancount

Created on 2024-10-07

@author: wf

Beancount

Encapsulates Beancount-specific operations and conversions

Source code in nomina/nomina_beancount.py
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
class Beancount:
    """
    Encapsulates Beancount-specific operations and conversions
    """

    def __init__(self):
        """
        constructor
        """
        self.entries: List[data.Directive] = []
        self.errors: List[str] = []
        self.options_map: Dict = {}

    def load_file(self, file_path: str) -> None:
        """
        Load a Beancount file

        Args:
            file_path (str): Path to the Beancount file
        """
        self.entries, self.errors, self.options_map = loader.load_file(file_path)

    def load_string(self, beancount_string: str) -> None:
        """
        Load Beancount data from a string

        Args:
            beancount_string (str): Beancount data as a string
        """
        self.entries, self.errors, self.options_map = loader.load_string(
            beancount_string
        )

    def add_entry(self, entry: data.Directive):
        """
        add the given entry to my entries
        """
        if entry:
            self.entries.append(entry)

    def firstToUpperCaseForSplits(self, s: str) -> str:
        parts = s.split(":")
        capitalized_parts = [
            part[0].upper() + part[1:] if part else "" for part in parts
        ]
        return ":".join(capitalized_parts)

    def sanitize_account_name(self, fq_name) -> str:
        """
        Sanitize the account name by replacing spaces, slashes, dots, commas,
        and removing paired square brackets but keeping the content inside.

        https://beancount.github.io/docs/beancount_language_syntax.html#syntax-overview
        """
        # Remove square brackets but keep the content inside using a named group
        fq_name = re.sub(r"\[(?P<content>.*?)\]", r"\g<content>", fq_name)
        # every character that is not a letter, a digit or a dash becomes a dash
        # (Beancount 3 accepts Unicode letters, so umlauts stay)
        fixed_name = re.sub(r"[^\w:-]", "-", fq_name).replace("_", "-")
        # each component starts with an upper case letter or a digit, see issue #15
        parts = []
        for part in fixed_name.split(":"):
            if part and not (part[0].isupper() or part[0].isdigit()):
                part = part[0].upper() + part[1:] if part[0].isalpha() else "X" + part
            parts.append(part)
        fixed_name = ":".join(parts)
        return fixed_name

    def create_open_directive(
        self,
        fq_account_name: str,
        date: date,
        currencies: Optional[List[str]] = None,
        meta: Optional[Dict] = None,
    ) -> data.Open:
        """
        Create a Beancount Open account directive

        Args:
            fq_account_name (str): fully qualifying Account name
            date (date): Opening date
            currencies (Optional[List[str]]): List of currencies for the account
            meta (Optional[Dict]): Metadata for the Open directive

        Returns:
            data.Open: Beancount Open directive
        """
        od = data.Open(meta or {}, date, fq_account_name, currencies or [], None)
        return od

    def create_transaction(
        self,
        date: date,
        description: str,
        postings: List[Tuple],
        payee: str = None,
        metadata: Dict = None,
    ) -> data.Transaction:
        """
        Create a Beancount Transaction directive

        Args:
            date (date): Transaction date
            description (str): Transaction description
            postings (List[Tuple]): List of (account, amount, currency) or (account, amount, currency, posting_meta) tuples
            payee (str, optional): Payee name
            metadata (Dict, optional): Transaction metadata

        Returns:
            data.Transaction: Beancount Transaction directive
        """
        meta = data.new_metadata("", 0, metadata)
        txn_postings = []
        for posting in postings:
            account, amount_value, currency = posting[:3]
            posting_meta = posting[3] if len(posting) > 3 else None
            if amount_value is None:
                pass
            else:
                amount_str = str(amount_value)
                amount_d = amount.D(amount_str)
                amt = amount.Amount(amount_d, currency)
                txn_postings.append(
                    data.Posting(account, amt, None, None, None, posting_meta)
                )

        tx = data.Transaction(
            meta,
            date,
            "*",
            payee,
            description,
            data.EMPTY_SET,
            data.EMPTY_SET,
            txn_postings,
        )
        return tx

    def entries_to_string(
        self, preamble: Preamble, entries: Optional[List[data.Directive]] = None
    ) -> str:
        """
        Get a text version of the entries, including the preamble.

        Args:
            preamble (Preamble): The preamble object to generate the header.
            entries (Optional[List[data.Directive]]): List of Beancount directives. If None, use self.entries.

        Returns:
            str: The Beancount file content as a string.
        """
        entries_to_print = entries if entries is not None else self.entries
        output = io.StringIO()

        # Add the preamble header
        if preamble:
            output.write(preamble.as_header())

        output.write("* Expenses\n")
        # Print entries to the output
        printer.print_entries(entries_to_print, file=output)

        return output.getvalue()

    def get_stats(self) -> Stats:
        """
        Get statistics about the Beancount data

        Returns:
            Stats: An object containing various statistics about the Beancount data
        """
        accounts = set()
        transactions = 0
        dates = []

        for entry in self.entries:
            if isinstance(entry, data.Open):
                accounts.add(entry.account)
            elif isinstance(entry, data.Transaction):
                transactions += 1
                dates.append(entry.date)

        start_date = min(dates) if dates else None
        end_date = max(dates) if dates else None

        return Stats(
            accounts=len(accounts),
            transactions=transactions,
            start_date=start_date,
            end_date=end_date,
            errors=len(self.errors),
            other={
                "commodities": len(
                    set(
                        entry.currency
                        for entry in self.entries
                        if isinstance(entry, data.Commodity)
                    )
                ),
            },
        )

__init__()

constructor

Source code in nomina/nomina_beancount.py
47
48
49
50
51
52
53
def __init__(self):
    """
    constructor
    """
    self.entries: List[data.Directive] = []
    self.errors: List[str] = []
    self.options_map: Dict = {}

add_entry(entry)

add the given entry to my entries

Source code in nomina/nomina_beancount.py
75
76
77
78
79
80
def add_entry(self, entry: data.Directive):
    """
    add the given entry to my entries
    """
    if entry:
        self.entries.append(entry)

create_open_directive(fq_account_name, date, currencies=None, meta=None)

Create a Beancount Open account directive

Parameters:

Name Type Description Default
fq_account_name str

fully qualifying Account name

required
date date

Opening date

required
currencies Optional[List[str]]

List of currencies for the account

None
meta Optional[Dict]

Metadata for the Open directive

None

Returns:

Type Description
Open

data.Open: Beancount Open directive

Source code in nomina/nomina_beancount.py
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def create_open_directive(
    self,
    fq_account_name: str,
    date: date,
    currencies: Optional[List[str]] = None,
    meta: Optional[Dict] = None,
) -> data.Open:
    """
    Create a Beancount Open account directive

    Args:
        fq_account_name (str): fully qualifying Account name
        date (date): Opening date
        currencies (Optional[List[str]]): List of currencies for the account
        meta (Optional[Dict]): Metadata for the Open directive

    Returns:
        data.Open: Beancount Open directive
    """
    od = data.Open(meta or {}, date, fq_account_name, currencies or [], None)
    return od

create_transaction(date, description, postings, payee=None, metadata=None)

Create a Beancount Transaction directive

Parameters:

Name Type Description Default
date date

Transaction date

required
description str

Transaction description

required
postings List[Tuple]

List of (account, amount, currency) or (account, amount, currency, posting_meta) tuples

required
payee str

Payee name

None
metadata Dict

Transaction metadata

None

Returns:

Type Description
Transaction

data.Transaction: Beancount Transaction directive

Source code in nomina/nomina_beancount.py
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
def create_transaction(
    self,
    date: date,
    description: str,
    postings: List[Tuple],
    payee: str = None,
    metadata: Dict = None,
) -> data.Transaction:
    """
    Create a Beancount Transaction directive

    Args:
        date (date): Transaction date
        description (str): Transaction description
        postings (List[Tuple]): List of (account, amount, currency) or (account, amount, currency, posting_meta) tuples
        payee (str, optional): Payee name
        metadata (Dict, optional): Transaction metadata

    Returns:
        data.Transaction: Beancount Transaction directive
    """
    meta = data.new_metadata("", 0, metadata)
    txn_postings = []
    for posting in postings:
        account, amount_value, currency = posting[:3]
        posting_meta = posting[3] if len(posting) > 3 else None
        if amount_value is None:
            pass
        else:
            amount_str = str(amount_value)
            amount_d = amount.D(amount_str)
            amt = amount.Amount(amount_d, currency)
            txn_postings.append(
                data.Posting(account, amt, None, None, None, posting_meta)
            )

    tx = data.Transaction(
        meta,
        date,
        "*",
        payee,
        description,
        data.EMPTY_SET,
        data.EMPTY_SET,
        txn_postings,
    )
    return tx

entries_to_string(preamble, entries=None)

Get a text version of the entries, including the preamble.

Parameters:

Name Type Description Default
preamble Preamble

The preamble object to generate the header.

required
entries Optional[List[Directive]]

List of Beancount directives. If None, use self.entries.

None

Returns:

Name Type Description
str str

The Beancount file content as a string.

Source code in nomina/nomina_beancount.py
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
def entries_to_string(
    self, preamble: Preamble, entries: Optional[List[data.Directive]] = None
) -> str:
    """
    Get a text version of the entries, including the preamble.

    Args:
        preamble (Preamble): The preamble object to generate the header.
        entries (Optional[List[data.Directive]]): List of Beancount directives. If None, use self.entries.

    Returns:
        str: The Beancount file content as a string.
    """
    entries_to_print = entries if entries is not None else self.entries
    output = io.StringIO()

    # Add the preamble header
    if preamble:
        output.write(preamble.as_header())

    output.write("* Expenses\n")
    # Print entries to the output
    printer.print_entries(entries_to_print, file=output)

    return output.getvalue()

get_stats()

Get statistics about the Beancount data

Returns:

Name Type Description
Stats Stats

An object containing various statistics about the Beancount data

Source code in nomina/nomina_beancount.py
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
def get_stats(self) -> Stats:
    """
    Get statistics about the Beancount data

    Returns:
        Stats: An object containing various statistics about the Beancount data
    """
    accounts = set()
    transactions = 0
    dates = []

    for entry in self.entries:
        if isinstance(entry, data.Open):
            accounts.add(entry.account)
        elif isinstance(entry, data.Transaction):
            transactions += 1
            dates.append(entry.date)

    start_date = min(dates) if dates else None
    end_date = max(dates) if dates else None

    return Stats(
        accounts=len(accounts),
        transactions=transactions,
        start_date=start_date,
        end_date=end_date,
        errors=len(self.errors),
        other={
            "commodities": len(
                set(
                    entry.currency
                    for entry in self.entries
                    if isinstance(entry, data.Commodity)
                )
            ),
        },
    )

load_file(file_path)

Load a Beancount file

Parameters:

Name Type Description Default
file_path str

Path to the Beancount file

required
Source code in nomina/nomina_beancount.py
55
56
57
58
59
60
61
62
def load_file(self, file_path: str) -> None:
    """
    Load a Beancount file

    Args:
        file_path (str): Path to the Beancount file
    """
    self.entries, self.errors, self.options_map = loader.load_file(file_path)

load_string(beancount_string)

Load Beancount data from a string

Parameters:

Name Type Description Default
beancount_string str

Beancount data as a string

required
Source code in nomina/nomina_beancount.py
64
65
66
67
68
69
70
71
72
73
def load_string(self, beancount_string: str) -> None:
    """
    Load Beancount data from a string

    Args:
        beancount_string (str): Beancount data as a string
    """
    self.entries, self.errors, self.options_map = loader.load_string(
        beancount_string
    )

sanitize_account_name(fq_name)

Sanitize the account name by replacing spaces, slashes, dots, commas, and removing paired square brackets but keeping the content inside.

https://beancount.github.io/docs/beancount_language_syntax.html#syntax-overview

Source code in nomina/nomina_beancount.py
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def sanitize_account_name(self, fq_name) -> str:
    """
    Sanitize the account name by replacing spaces, slashes, dots, commas,
    and removing paired square brackets but keeping the content inside.

    https://beancount.github.io/docs/beancount_language_syntax.html#syntax-overview
    """
    # Remove square brackets but keep the content inside using a named group
    fq_name = re.sub(r"\[(?P<content>.*?)\]", r"\g<content>", fq_name)
    # every character that is not a letter, a digit or a dash becomes a dash
    # (Beancount 3 accepts Unicode letters, so umlauts stay)
    fixed_name = re.sub(r"[^\w:-]", "-", fq_name).replace("_", "-")
    # each component starts with an upper case letter or a digit, see issue #15
    parts = []
    for part in fixed_name.split(":"):
        if part and not (part[0].isupper() or part[0].isdigit()):
            part = part[0].upper() + part[1:] if part[0].isalpha() else "X" + part
        parts.append(part)
    fixed_name = ":".join(parts)
    return fixed_name

nomina_cmd

Created on 2024-10-06

@author: wf

NominaCmd

Bases: WebserverCmd

command line handling for nomina

Source code in nomina/nomina_cmd.py
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
class NominaCmd(WebserverCmd):
    """
    command line handling for nomina
    """

    def __init__(self):
        """
        constructor
        """
        config = NominaWebServer.get_config()
        WebserverCmd.__init__(self, config, NominaWebServer, DEBUG)
        pass

    def getArgParser(self, description: str, version_msg) -> ArgumentParser:
        """
        override the default argparser call
        """
        parser = super().getArgParser(description, version_msg)
        parser.add_argument(
            "-rp",
            "--root_path",
            default=NominaWebServer.examples_path(),
            help="path to nomina files [default: %(default)s]",
        )
        parser.add_argument(
            "--convert",
            type=Path,
            help="Convert the specified file to the desired format",
        )
        parser.add_argument(
            "--format",
            choices=["LB-YAML", "GC-XML", "BEAN"],
            default="LB-YAML",
            help="Output format for conversion [default: %(default)s]",
        )
        parser.add_argument(
            "-o",
            "--output",
            type=Path,
            help="Output file",
        )
        parser.add_argument(
            "--vat-codes",
            dest="vat_codes",
            type=Path,
            help="VAT code map yaml file [default: nomina_examples/vat_codes.yaml]",
        )
        return parser

    def handle_args(self, args) -> bool:
        """
        handle the command line args
        """
        # Call the superclass handle_args to maintain base class behavior
        handled = super().handle_args(args)
        self.debug = self.args.debug
        args = self.args
        if args.convert:
            if not args.output:
                print("Error: --output must be specified when using --convert.")
                self.parser.print_help()  # Print usage
                self.exit_code = 1
            else:
                converter = Converter(args)
                converter.convert()
            handled = True
        return handled

__init__()

constructor

Source code in nomina/nomina_cmd.py
22
23
24
25
26
27
28
def __init__(self):
    """
    constructor
    """
    config = NominaWebServer.get_config()
    WebserverCmd.__init__(self, config, NominaWebServer, DEBUG)
    pass

getArgParser(description, version_msg)

override the default argparser call

Source code in nomina/nomina_cmd.py
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def getArgParser(self, description: str, version_msg) -> ArgumentParser:
    """
    override the default argparser call
    """
    parser = super().getArgParser(description, version_msg)
    parser.add_argument(
        "-rp",
        "--root_path",
        default=NominaWebServer.examples_path(),
        help="path to nomina files [default: %(default)s]",
    )
    parser.add_argument(
        "--convert",
        type=Path,
        help="Convert the specified file to the desired format",
    )
    parser.add_argument(
        "--format",
        choices=["LB-YAML", "GC-XML", "BEAN"],
        default="LB-YAML",
        help="Output format for conversion [default: %(default)s]",
    )
    parser.add_argument(
        "-o",
        "--output",
        type=Path,
        help="Output file",
    )
    parser.add_argument(
        "--vat-codes",
        dest="vat_codes",
        type=Path,
        help="VAT code map yaml file [default: nomina_examples/vat_codes.yaml]",
    )
    return parser

handle_args(args)

handle the command line args

Source code in nomina/nomina_cmd.py
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def handle_args(self, args) -> bool:
    """
    handle the command line args
    """
    # Call the superclass handle_args to maintain base class behavior
    handled = super().handle_args(args)
    self.debug = self.args.debug
    args = self.args
    if args.convert:
        if not args.output:
            print("Error: --output must be specified when using --convert.")
            self.parser.print_help()  # Print usage
            self.exit_code = 1
        else:
            converter = Converter(args)
            converter.convert()
        handled = True
    return handled

main(argv=None)

main call

Source code in nomina/nomina_cmd.py
86
87
88
89
90
91
92
def main(argv: list = None):
    """
    main call
    """
    cmd = NominaCmd()
    exit_code = cmd.cmd_main(argv)
    return exit_code

nomina_converter

Created on 2024-10-06

@author: wf

AccountingFileConverter

Abstract base class for accounting file converters. This class provides a structure for converting accounting data from one format to another.

Source code in nomina/nomina_converter.py
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
class AccountingFileConverter:
    """
    Abstract base class for accounting file converters.
    This class provides a structure for converting accounting data from one format to another.
    """

    def __init__(
        self,
        from_format_acronym: str,
        to_format_acronym: str,
        debug: bool = False,
    ):
        """
        Constructor that initializes the converter instance.

        Args:
            from_format_acronym (str): Acronym of the source format
            to_format_acronym (str): Acronym of the target format
            debug (bool): If True, enable debug output
        """
        formats = AccountingFileFormats()
        self.from_format: AccountingFileFormat = formats.get_by_acronym(
            from_format_acronym
        )
        self.to_format: AccountingFileFormat = formats.get_by_acronym(to_format_acronym)
        self.debug: bool = debug
        self.source: Optional[object] = None
        self.target: Optional[object] = None
        self.log: Log = Log()

    def load(self, input_stream: TextIO) -> object:
        """
        Load the content from the input stream.

        Args:
            input_stream (TextIO): The input stream

        Returns:
            object: The loaded content

        Raises:
            ValueError: If called on the abstract base class.
        """
        raise ValueError("load must be implemented in the subclass")

    def convert_to_target(self) -> object:
        """
        Convert the loaded source content to the target format.

        Returns:
            object: The converted content object (could be any personal accounting book type).

        Raises:
            ValueError: If called on the abstract base class.
        """
        raise ValueError("convert_to_target must be implemented in the subclass")

    def to_text(self) -> str:
        """
        Convert the target object into a text representation.

        Returns:
            str: The text representation of the target content.

        Raises:
            ValueError: If not implemented by a subclass.
        """
        raise ValueError("to_text must be implemented in the subclass")

    def show_stats(self) -> None:
        """
        Display statistics about the source and target objects.
        """
        source_stats = self.source.get_stats()
        if self.debug:
            source_stats.show()
        target_stats = self.target.get_stats()
        if self.debug:
            target_stats.show()

__init__(from_format_acronym, to_format_acronym, debug=False)

Constructor that initializes the converter instance.

Parameters:

Name Type Description Default
from_format_acronym str

Acronym of the source format

required
to_format_acronym str

Acronym of the target format

required
debug bool

If True, enable debug output

False
Source code in nomina/nomina_converter.py
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def __init__(
    self,
    from_format_acronym: str,
    to_format_acronym: str,
    debug: bool = False,
):
    """
    Constructor that initializes the converter instance.

    Args:
        from_format_acronym (str): Acronym of the source format
        to_format_acronym (str): Acronym of the target format
        debug (bool): If True, enable debug output
    """
    formats = AccountingFileFormats()
    self.from_format: AccountingFileFormat = formats.get_by_acronym(
        from_format_acronym
    )
    self.to_format: AccountingFileFormat = formats.get_by_acronym(to_format_acronym)
    self.debug: bool = debug
    self.source: Optional[object] = None
    self.target: Optional[object] = None
    self.log: Log = Log()

convert_to_target()

Convert the loaded source content to the target format.

Returns:

Name Type Description
object object

The converted content object (could be any personal accounting book type).

Raises:

Type Description
ValueError

If called on the abstract base class.

Source code in nomina/nomina_converter.py
60
61
62
63
64
65
66
67
68
69
70
def convert_to_target(self) -> object:
    """
    Convert the loaded source content to the target format.

    Returns:
        object: The converted content object (could be any personal accounting book type).

    Raises:
        ValueError: If called on the abstract base class.
    """
    raise ValueError("convert_to_target must be implemented in the subclass")

load(input_stream)

Load the content from the input stream.

Parameters:

Name Type Description Default
input_stream TextIO

The input stream

required

Returns:

Name Type Description
object object

The loaded content

Raises:

Type Description
ValueError

If called on the abstract base class.

Source code in nomina/nomina_converter.py
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def load(self, input_stream: TextIO) -> object:
    """
    Load the content from the input stream.

    Args:
        input_stream (TextIO): The input stream

    Returns:
        object: The loaded content

    Raises:
        ValueError: If called on the abstract base class.
    """
    raise ValueError("load must be implemented in the subclass")

show_stats()

Display statistics about the source and target objects.

Source code in nomina/nomina_converter.py
84
85
86
87
88
89
90
91
92
93
def show_stats(self) -> None:
    """
    Display statistics about the source and target objects.
    """
    source_stats = self.source.get_stats()
    if self.debug:
        source_stats.show()
    target_stats = self.target.get_stats()
    if self.debug:
        target_stats.show()

to_text()

Convert the target object into a text representation.

Returns:

Name Type Description
str str

The text representation of the target content.

Raises:

Type Description
ValueError

If not implemented by a subclass.

Source code in nomina/nomina_converter.py
72
73
74
75
76
77
78
79
80
81
82
def to_text(self) -> str:
    """
    Convert the target object into a text representation.

    Returns:
        str: The text representation of the target content.

    Raises:
        ValueError: If not implemented by a subclass.
    """
    raise ValueError("to_text must be implemented in the subclass")

BaseFromLedgerConverter

Bases: AccountingFileConverter

Base class for converters that convert from LedgerBook format to various formats.

Source code in nomina/nomina_converter.py
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
class BaseFromLedgerConverter(AccountingFileConverter):
    """
    Base class for converters that convert from LedgerBook format to various formats.
    """

    def __init__(self, to_format_acronym: str, debug: bool = False):
        """
        Constructor for BaseFromLedgerConverter.

        Args:
            to_format_acronym (str): Acronym of the target format
            debug (bool): If True, enable debug output
        """
        super().__init__("LB-YAML", to_format_acronym, debug)

    def convert_from_ledger(self, ledger_book: Book) -> object:
        """
        Convert from LedgerBook format to the target format object.

        Args:
            ledger_book (Book): The LedgerBook object to convert

        Returns:
            object: The converted object in the target format
        """
        self.set_source(ledger_book)
        if self.debug:
            print(
                f"Converting Ledger Book {ledger_book.name} to {self.to_format.acronym}"
            )
        self.target = self.convert_to_target()
        self.show_stats()
        return self.target

    def to_text(self, target: object) -> str:
        """
        Convert the target object into a text representation.

        Args:
            target (object): The target object to convert to text

        Returns:
            str: The text representation of the target content.

        Raises:
            ValueError: If not implemented by a subclass.
        """
        raise ValueError("to_text must be implemented in the subclass")

__init__(to_format_acronym, debug=False)

Constructor for BaseFromLedgerConverter.

Parameters:

Name Type Description Default
to_format_acronym str

Acronym of the target format

required
debug bool

If True, enable debug output

False
Source code in nomina/nomina_converter.py
136
137
138
139
140
141
142
143
144
def __init__(self, to_format_acronym: str, debug: bool = False):
    """
    Constructor for BaseFromLedgerConverter.

    Args:
        to_format_acronym (str): Acronym of the target format
        debug (bool): If True, enable debug output
    """
    super().__init__("LB-YAML", to_format_acronym, debug)

convert_from_ledger(ledger_book)

Convert from LedgerBook format to the target format object.

Parameters:

Name Type Description Default
ledger_book Book

The LedgerBook object to convert

required

Returns:

Name Type Description
object object

The converted object in the target format

Source code in nomina/nomina_converter.py
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def convert_from_ledger(self, ledger_book: Book) -> object:
    """
    Convert from LedgerBook format to the target format object.

    Args:
        ledger_book (Book): The LedgerBook object to convert

    Returns:
        object: The converted object in the target format
    """
    self.set_source(ledger_book)
    if self.debug:
        print(
            f"Converting Ledger Book {ledger_book.name} to {self.to_format.acronym}"
        )
    self.target = self.convert_to_target()
    self.show_stats()
    return self.target

to_text(target)

Convert the target object into a text representation.

Parameters:

Name Type Description Default
target object

The target object to convert to text

required

Returns:

Name Type Description
str str

The text representation of the target content.

Raises:

Type Description
ValueError

If not implemented by a subclass.

Source code in nomina/nomina_converter.py
165
166
167
168
169
170
171
172
173
174
175
176
177
178
def to_text(self, target: object) -> str:
    """
    Convert the target object into a text representation.

    Args:
        target (object): The target object to convert to text

    Returns:
        str: The text representation of the target content.

    Raises:
        ValueError: If not implemented by a subclass.
    """
    raise ValueError("to_text must be implemented in the subclass")

BaseToLedgerConverter

Bases: AccountingFileConverter

Base class for converters that convert from various formats to LedgerBook format.

Source code in nomina/nomina_converter.py
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
class BaseToLedgerConverter(AccountingFileConverter):
    """
    Base class for converters that convert from various formats to LedgerBook format.
    """

    def __init__(self, from_format_acronym: str, debug: bool = False):
        """
        Constructor for BaseToLedgerConverter.

        Args:
            from_format_acronym (str): Acronym of the source format
            debug (bool): If True, enable debug output
        """
        super().__init__(from_format_acronym, "LB-YAML", debug)

    def convert_to_ledger(self, input_path: str) -> Book:
        """
        Convert the input file to LedgerBook format.

        Args:
            input_path (str): Path to the input file

        Returns:
            Book: The converted LedgerBook object
        """
        if self.debug:
            print(f"Loading {self.from_format.name} from {input_path}")
        self.source = self.load(input_path)
        if self.debug:
            print(f"Converting {self.from_format.acronym} to {self.to_format.acronym}")
        self.target = self.convert_to_target()
        self.show_stats()
        return self.target

__init__(from_format_acronym, debug=False)

Constructor for BaseToLedgerConverter.

Parameters:

Name Type Description Default
from_format_acronym str

Acronym of the source format

required
debug bool

If True, enable debug output

False
Source code in nomina/nomina_converter.py
101
102
103
104
105
106
107
108
109
def __init__(self, from_format_acronym: str, debug: bool = False):
    """
    Constructor for BaseToLedgerConverter.

    Args:
        from_format_acronym (str): Acronym of the source format
        debug (bool): If True, enable debug output
    """
    super().__init__(from_format_acronym, "LB-YAML", debug)

convert_to_ledger(input_path)

Convert the input file to LedgerBook format.

Parameters:

Name Type Description Default
input_path str

Path to the input file

required

Returns:

Name Type Description
Book Book

The converted LedgerBook object

Source code in nomina/nomina_converter.py
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def convert_to_ledger(self, input_path: str) -> Book:
    """
    Convert the input file to LedgerBook format.

    Args:
        input_path (str): Path to the input file

    Returns:
        Book: The converted LedgerBook object
    """
    if self.debug:
        print(f"Loading {self.from_format.name} from {input_path}")
    self.source = self.load(input_path)
    if self.debug:
        print(f"Converting {self.from_format.acronym} to {self.to_format.acronym}")
    self.target = self.convert_to_target()
    self.show_stats()
    return self.target

qif

Created on 2024-10-01

Quicken Interchange Format (QIF) Parser see https://en.wikipedia.org/wiki/Quicken_Interchange_Format

@author: wf

Category dataclass

Bases: ParseRecord

a QIF tag (Class or Category)

Source code in nomina/qif.py
91
92
93
94
95
96
97
98
@lod_storable
class Category(ParseRecord):
    """
    a QIF tag (Class or Category)
    """

    name: Optional[str] = None
    description: str = ""

ParseRecord dataclass

generic parse record to keep track of lines and errors

Source code in nomina/qif.py
25
26
27
28
29
30
31
32
33
@dataclass
class ParseRecord:
    """
    generic parse record to keep track of lines and errors
    """

    start_line: int = 0
    end_line: int = 0
    errors: Dict[str, Exception] = field(default_factory=dict)

QifClass dataclass

Bases: ParseRecord

a QIF tag (Class or Category)

Source code in nomina/qif.py
101
102
103
104
105
106
107
108
@lod_storable
class QifClass(ParseRecord):
    """
    a QIF tag (Class or Category)
    """

    name: Optional[str] = None
    description: str = ""

QifField

A QIF field with possible context-dependent meanings for the marker used e.g. D for isodate or description and T for amount or account_type marker meaning might also be unclear - denoted by a None field_name

Source code in nomina/qif.py
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
class QifField:
    """
    A QIF field with possible
    context-dependent meanings for the marker used e.g. D for isodate or description and
    T for amount or account_type
    marker meaning might also be unclear - denoted by a None field_name

    """

    def __init__(
        self, marker: str, field_name: str = None, context_fields: Dict[str, str] = None
    ):
        """
        Args:
            marker: QIF marker character
            field_name: default field name, None if unclear
            context_fields: optional mapping of record_type to field_name
        """
        self.marker = marker
        self.field_name = f"{marker}?" if field_name is None else field_name
        self.context_fields = context_fields if context_fields else {}

    def resolve(self, record_type: str) -> str:
        """get field name based on record type context"""
        field_name = self.context_fields.get(record_type, self.field_name)
        return field_name

    def add_line_value_to_record(
        self, line: str, record_type: str, current_record: dict
    ):
        """
        handle a QIF line for this field by adding the value
        to the record with the field being resolved according
        to our marker and the record type it should be applied to

        Args:
            line: the raw QIF line
            record_type: the record type context
            current_record: the record being built
        """
        value = line[1:].strip()
        key = self.resolve(record_type)
        if key in ["split_category", "split_memo", "split_amount"]:
            if key == "split_category":
                value = SplitCategory(value)
            if key not in current_record:
                current_record[key] = []
            current_record[key].append(value)
        else:
            current_record[key] = value

__init__(marker, field_name=None, context_fields=None)

Parameters:

Name Type Description Default
marker str

QIF marker character

required
field_name str

default field name, None if unclear

None
context_fields Dict[str, str]

optional mapping of record_type to field_name

None
Source code in nomina/qif.py
216
217
218
219
220
221
222
223
224
225
226
227
def __init__(
    self, marker: str, field_name: str = None, context_fields: Dict[str, str] = None
):
    """
    Args:
        marker: QIF marker character
        field_name: default field name, None if unclear
        context_fields: optional mapping of record_type to field_name
    """
    self.marker = marker
    self.field_name = f"{marker}?" if field_name is None else field_name
    self.context_fields = context_fields if context_fields else {}

add_line_value_to_record(line, record_type, current_record)

handle a QIF line for this field by adding the value to the record with the field being resolved according to our marker and the record type it should be applied to

Parameters:

Name Type Description Default
line str

the raw QIF line

required
record_type str

the record type context

required
current_record dict

the record being built

required
Source code in nomina/qif.py
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
def add_line_value_to_record(
    self, line: str, record_type: str, current_record: dict
):
    """
    handle a QIF line for this field by adding the value
    to the record with the field being resolved according
    to our marker and the record type it should be applied to

    Args:
        line: the raw QIF line
        record_type: the record type context
        current_record: the record being built
    """
    value = line[1:].strip()
    key = self.resolve(record_type)
    if key in ["split_category", "split_memo", "split_amount"]:
        if key == "split_category":
            value = SplitCategory(value)
        if key not in current_record:
            current_record[key] = []
        current_record[key].append(value)
    else:
        current_record[key] = value

resolve(record_type)

get field name based on record type context

Source code in nomina/qif.py
229
230
231
232
def resolve(self, record_type: str) -> str:
    """get field name based on record type context"""
    field_name = self.context_fields.get(record_type, self.field_name)
    return field_name

SimpleQifParser

a QIF parser

Source code in nomina/qif.py
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
@lod_storable
class SimpleQifParser:
    """
    a QIF parser
    """

    name: Optional[str] = None
    currency: str = "EUR"
    default_account_type = "EXPENSE"
    default_category = "UndefinedCategory"
    options: Dict[str, str] = field(default_factory=dict)
    classes: Dict[str, QifClass] = field(default_factory=dict)
    categories: Dict[str, Category] = field(default_factory=dict)
    accounts: Dict[str, Account] = field(default_factory=dict)
    transactions: Dict[str, Transaction] = field(default_factory=dict)
    accounts: Dict[str, Account] = field(default_factory=dict)
    errors: List[ErrorRecord] = field(default_factory=list)

    def __post_init__(self):
        self.current_account = None
        self.qif_fields = {
            "$": QifField("$", "split_amount"),
            "~": QifField("~"),
            "&": QifField("&"),
            "%": QifField("%"),
            "@": QifField("@"),
            "A": QifField("A", "address"),
            "B": QifField("B"),
            "C": QifField("C", "cleared"),
            "D": QifField(
                "D", "isodate", {"Cat": "description", "Class": "description"}
            ),
            "E": QifField("E", "split_memo"),
            "F": QifField("F"),
            "G": QifField("G"),
            "I": QifField("I"),
            "K": QifField("K"),
            "L": QifField("L", "category"),
            "M": QifField("M", "memo"),
            "N": QifField("N", "name"),
            "O": QifField("O"),
            "R": QifField("R"),
            "P": QifField("P", "payee"),
            "Q": QifField("Q"),
            "S": QifField("S", "split_category"),
            "T": QifField("T", "amount", {"Account": "account_type"}),
            "U": QifField("U", "amount_unknown"),
            "V": QifField("V"),
            "Y": QifField("Y"),
        }

    def parse_file(
        self,
        qif_file: str,
        encoding="iso-8859-1",
        name: str = None,
        verbose: bool = False,
        debug: bool = False,
    ):
        """
        parse a qif file

        Args:
            qif_file (str): Path to the input QIF file.
            encoding (str): File encoding. Defaults to 'iso-8859-1'.
            name (str): name to set if None use the basename of the qif_file
            verbose (bool): if True give verbose output
            debug (bool): if True show debug output
        """
        if name is None:
            name = os.path.basename(qif_file)
        self.name = name
        with open(qif_file, "r", encoding=encoding) as file:
            content = file.readlines()
        self.parse(content, verbose=verbose, debug=debug)

    def parse(self, lines: List[str], verbose: bool = False, debug: bool = False):
        """
        parse the given list of lines
        """
        current_record = {}
        record_type = None
        start_line = 1

        for line_num, line in enumerate(lines, 1):
            line = line.strip()
            if not line:
                continue
            if debug:
                print(f"{line_num}:{line}")
            if line.startswith("$"):
                self.currency = "USD"
            elif line.startswith("€"):
                self.currency = "EUR"
            if line.startswith("!Option:"):
                option = line[8:]
                self.options[option] = True
            elif line.startswith("!Clear:"):
                option = line[8:]
                self.options[option] = False
            elif line.startswith("!Type:") or line.startswith("!Account"):
                if current_record:
                    self._add_record(
                        record_type, current_record, start_line, line_num - 1
                    )
                if line.startswith("!Account"):
                    record_type = "Account"
                else:
                    record_type = line[6:]  # Text after !Type:
                    pass
                current_record = {}
                start_line = line_num + 1
            elif line == "^":
                if current_record:
                    self._add_record(record_type, current_record, start_line, line_num)
                current_record = {}
                start_line = line_num + 1

            elif line[0] in self.qif_fields:
                marker = line[0]
                qif_field = self.qif_fields[marker]
                qif_field.add_line_value_to_record(line, record_type, current_record)
            else:
                error = ErrorRecord(start_line=start_line, end_line=line_num, line=line)
                err_msg = f"parser can not handle line {line_num}: {line}"
                if verbose or debug:
                    logging.error(err_msg)
                self.errors.append(error)

        if current_record:
            self._add_record(record_type, current_record, start_line, len(lines))

    def _add_account(
        self,
        account_name: str,
        account_type: str,
        description: str,
        start_line,
        end_line,
    ) -> Account:
        """
        add an account for the given parameters making sure the parent account is created if need be
        """
        parts = account_name.split(":")
        name = parts[-1]
        parent_name = ":".join(parts[:-1]) if len(parts) > 1 else None
        parent_id = parent_name
        if account_type is None:
            account_type = self.default_account_type
        if parent_name and parent_name not in self.accounts:
            self.accounts[parent_name] = Account(
                name=parent_name,
                account_type=account_type,
                currency=self.currency,
                start_line=start_line,
                end_line=end_line,
            )
        account = Account(
            name=name,
            description=description,
            account_type=account_type,
            currency=self.currency,
            parent_account_id=parent_id,
            start_line=start_line,
            end_line=end_line,
        )
        self.accounts[account.name] = account
        return account

    def _add_record(
        self, record_type: str, record: Dict[str, Any], start_line: int, end_line: int
    ):
        """
        add the given record
        """
        record["_start_line"] = start_line
        record["_end_line"] = end_line
        if record_type == "Account":
            # @TODO allow external lookup of currency since quicken does not have it
            # Determine if the account has a parent by checking for a ':' in the name
            account_name = record.get("name", "")
            account_type = account_type = record.get("account_type")
            description = record.get("description", "")
            self.current_account = self._add_account(
                account_name,
                account_type=account_type,
                description=description,
                start_line=start_line,
                end_line=end_line,
            )
        elif record_type == "Class":
            qclass = QifClass(
                name=record.get("name", ""),
                description=record.get("description", ""),
                start_line=start_line,
                end_line=end_line,
            )
            self.classes[qclass.name] = qclass
        elif record_type == "Cat":
            cat = Category(
                name=record.get("name", ""),
                description=record.get("description", ""),
                start_line=start_line,
                end_line=end_line,
            )
            self.categories[cat.name] = cat
        else:
            tx = self.tx_for_record(record)
            if self.current_account:
                tx.account = self.current_account
                account_name = self.current_account.name
                tx_id = f"{account_name}:{tx.isodate}:{tx.start_line}"
            else:
                tx_id = f"{tx.isodate}:{tx.start_line}"

            self.transactions[tx_id] = tx

    def tx_for_record(self, t):
        """
        convert the transaction record
        """
        transaction = Transaction(start_line=t["_start_line"], end_line=t["_end_line"])
        # the S, E and $ lines are collected under the singular field names
        plural_keys = {
            "split_category": "split_categories",
            "split_memo": "split_memos",
            "split_amount": "split_amounts",
        }
        for key, value in t.items():
            if key.startswith("_"):
                continue
            setattr(transaction, plural_keys.get(key, key), value)
        transaction.normalize(date_formats=self.date_formats())
        return transaction

    def date_formats(self) -> Optional[List[str]]:
        """
        the date formats of this file: month first when the file declares !Option:MDY
        (Finanzmanager Deluxe and Quicken exports), else the defaults of DateUtils

        Returns:
            list: the formats or None for the defaults
        """
        date_formats = None
        if self.options.get("MDY"):
            date_formats = ["%m.%d.%y", "%m/%d/%y", "%m/%d/%Y", "%Y-%m-%d"]
        return date_formats

    def get_lod(self) -> List[Dict[str, Any]]:
        """
        Get a list of dictionaries representing all transactions.

        Returns:
            List[Dict[str, Any]]: A list of dictionaries, each representing a transaction.
        """
        lod = []
        for tx in self.transactions.values():
            split_category = None
            if tx.split_categories:
                split_category = ",".join(tx.split_categories)
            split_memo = None
            if tx.split_memos:
                split_memo = ",".join(tx.split_memos)
            split_amount = None
            if tx.split_amounts:
                split_amount = ",".join(map(str, tx.split_amounts))
            record = {
                # "tx_id": f"{self.current_account.name}:{tx.isodate}:{tx.start_line}",
                # "account": self.current_account.name,
                "isodate": tx.isodate,
                "amount": tx.amount,
                "payee": tx.payee,
                "memo": tx.memo,
                "category": tx.category,
                "number": tx.number,
                "cleared": tx.cleared,
                "address": tx.address,
                "split_category": split_category,
                "split_memo": split_memo,
                "split_amount": split_amount,
                "qif_class": tx.qif_class.name if tx.qif_class else None,
            }
            lod.append(record)
        return lod

    def print_sample_transactions(self, num_samples: int = 7):
        print(f"\nSample of {min(num_samples, len(self.transactions))} transactions:")
        txs = list(self.transactions.values())[:num_samples]
        for idx, transaction in enumerate(txs, 1):
            print(
                f"Transaction {idx} (lines {transaction.start_line}-{transaction.end_line}):"
            )
            for field, value in vars(transaction).items():
                if field not in ["start_line", "end_line", "errors"]:
                    if isinstance(value, list):
                        print(f"  {field}: {', '.join(map(str, value))}")
                    else:
                        print(f"  {field}: {value}")
            if transaction.errors:
                print("  Errors:")
                for field, error in transaction.errors.items():
                    print(f"    {field}: {type(error).__name__}: {str(error)}")
            print()

    def print_parts(self, parts: dict, title: str, limit: int = 100000):
        print(f"\n{title}:")
        for i, part in enumerate(parts.values(), start=1):
            if i >= limit:
                break
            print(
                f"{i:3}: {part.name} - {part.description} (#{part.start_line}-{part.end_line})"
            )

    def get_stats(self) -> Stats:
        dates = [
            datetime.strptime(tx.isodate, "%Y-%m-%d")
            for tx in self.transactions.values()
            if tx.isodate
        ]
        if dates:
            min_date = min(dates).strftime("%Y-%m-%d")
            max_date = max(dates).strftime("%Y-%m-%d")
        else:
            min_date = max_date = None

        other_stats = {
            "options": self.options,
            "field_histogram": self._get_field_histogram(),
            "error_histogram": self._get_error_histogram(),
        }

        return Stats(
            accounts=len(self.accounts),
            transactions=len(self.transactions),
            start_date=min_date,
            end_date=max_date,
            classes=len(self.classes),
            categories=len(self.categories),
            errors=len(self.errors),
            other=other_stats,
        )

    def _get_field_histogram(self) -> Dict[str, int]:
        field_counter = Counter()
        for transaction in self.transactions.values():
            for field, value in vars(transaction).items():
                if field not in ["start_line", "end_line", "errors"]:
                    if value is not None and (
                        not isinstance(value, list) or len(value) > 0
                    ):
                        field_counter[field] += 1
        return dict(field_counter)

    def _get_error_histogram(self) -> Dict[str, int]:
        error_counter = Counter()
        for transaction in self.transactions.values():
            error_counter.update(transaction.errors.keys())
        return dict(error_counter)

    def generate_error_report(self, max_errors_per_type=10):
        """
        Generate a detailed error report.

        Args:
            max_errors_per_type (int): Maximum number of errors to show for each error type.

        Returns:
            str: A formatted error report.
        """
        error_types = {}
        for transaction in self.transactions.values():
            for field, error in transaction.errors.items():
                error_type = type(error).__name__
                if error_type not in error_types:
                    error_types[error_type] = []
                error_types[error_type].append((transaction, field, error))

        report = ["Detailed Error Report:"]
        for error_type, errors in error_types.items():
            report.append(f"\n{error_type} ({len(errors)} occurrences):")
            for i, (transaction, field, error) in enumerate(
                errors[:max_errors_per_type], 1
            ):
                report.append(
                    f"  {i}. Line {transaction.start_line}-{transaction.end_line}, Field: {field}"
                )
                report.append(f"     Error: {str(error)}")
                report.append(
                    f"     Transaction: {self.transaction_summary(transaction)}"
                )
            if len(errors) > max_errors_per_type:
                report.append(f"  ... and {len(errors) - max_errors_per_type} more.")

        return "\n".join(report)

    def transaction_summary(self, transaction):
        """Helper function to provide a summary of a transaction."""
        summary = []
        for field, value in vars(transaction).items():
            if field not in ["start_line", "end_line", "errors"] and value is not None:
                summary.append(f"{field}: {value}")
        return ", ".join(summary)

    def show_summary(self, limit: int = 7):
        stats = self.get_stats()
        self.stats = stats

        # Display basic statistics
        print(f"Options: {stats.other.get('options', {})}")
        print(f"#classes: {stats.classes}")
        print(f"#categories: {stats.categories}")
        print(f"#accounts: {stats.accounts}")
        print(f"#transactions: {stats.transactions}")
        print(f"#errors: {stats.errors}")
        print(f"Date range: {stats.start_date} to {stats.end_date}")

        # Display field and error histograms
        print("Field histogram:")
        field_histogram = stats.other.get("field_histogram", {})
        for field, count in field_histogram.items():
            print(f"  {field}: {count}")

        print("Error histogram:")
        error_histogram = stats.other.get("error_histogram", {})
        for field, count in error_histogram.items():
            print(f"  {field}: {count}")

        # Display parts
        self.print_parts(self.accounts, "Accounts", limit=limit)
        self.print_parts(self.classes, "Classes", limit=limit)
        self.print_parts(self.categories, "Categories", limit=limit)

        # Display sample transactions
        print("\nSample Transactions:")
        self.print_sample_transactions()

        # Generate and display error report
        error_report = self.generate_error_report()
        print(error_report)

date_formats()

the date formats of this file: month first when the file declares !Option:MDY (Finanzmanager Deluxe and Quicken exports), else the defaults of DateUtils

Returns:

Name Type Description
list Optional[List[str]]

the formats or None for the defaults

Source code in nomina/qif.py
494
495
496
497
498
499
500
501
502
503
504
505
def date_formats(self) -> Optional[List[str]]:
    """
    the date formats of this file: month first when the file declares !Option:MDY
    (Finanzmanager Deluxe and Quicken exports), else the defaults of DateUtils

    Returns:
        list: the formats or None for the defaults
    """
    date_formats = None
    if self.options.get("MDY"):
        date_formats = ["%m.%d.%y", "%m/%d/%y", "%m/%d/%Y", "%Y-%m-%d"]
    return date_formats

generate_error_report(max_errors_per_type=10)

Generate a detailed error report.

Parameters:

Name Type Description Default
max_errors_per_type int

Maximum number of errors to show for each error type.

10

Returns:

Name Type Description
str

A formatted error report.

Source code in nomina/qif.py
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
def generate_error_report(self, max_errors_per_type=10):
    """
    Generate a detailed error report.

    Args:
        max_errors_per_type (int): Maximum number of errors to show for each error type.

    Returns:
        str: A formatted error report.
    """
    error_types = {}
    for transaction in self.transactions.values():
        for field, error in transaction.errors.items():
            error_type = type(error).__name__
            if error_type not in error_types:
                error_types[error_type] = []
            error_types[error_type].append((transaction, field, error))

    report = ["Detailed Error Report:"]
    for error_type, errors in error_types.items():
        report.append(f"\n{error_type} ({len(errors)} occurrences):")
        for i, (transaction, field, error) in enumerate(
            errors[:max_errors_per_type], 1
        ):
            report.append(
                f"  {i}. Line {transaction.start_line}-{transaction.end_line}, Field: {field}"
            )
            report.append(f"     Error: {str(error)}")
            report.append(
                f"     Transaction: {self.transaction_summary(transaction)}"
            )
        if len(errors) > max_errors_per_type:
            report.append(f"  ... and {len(errors) - max_errors_per_type} more.")

    return "\n".join(report)

get_lod()

Get a list of dictionaries representing all transactions.

Returns:

Type Description
List[Dict[str, Any]]

List[Dict[str, Any]]: A list of dictionaries, each representing a transaction.

Source code in nomina/qif.py
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
def get_lod(self) -> List[Dict[str, Any]]:
    """
    Get a list of dictionaries representing all transactions.

    Returns:
        List[Dict[str, Any]]: A list of dictionaries, each representing a transaction.
    """
    lod = []
    for tx in self.transactions.values():
        split_category = None
        if tx.split_categories:
            split_category = ",".join(tx.split_categories)
        split_memo = None
        if tx.split_memos:
            split_memo = ",".join(tx.split_memos)
        split_amount = None
        if tx.split_amounts:
            split_amount = ",".join(map(str, tx.split_amounts))
        record = {
            # "tx_id": f"{self.current_account.name}:{tx.isodate}:{tx.start_line}",
            # "account": self.current_account.name,
            "isodate": tx.isodate,
            "amount": tx.amount,
            "payee": tx.payee,
            "memo": tx.memo,
            "category": tx.category,
            "number": tx.number,
            "cleared": tx.cleared,
            "address": tx.address,
            "split_category": split_category,
            "split_memo": split_memo,
            "split_amount": split_amount,
            "qif_class": tx.qif_class.name if tx.qif_class else None,
        }
        lod.append(record)
    return lod

parse(lines, verbose=False, debug=False)

parse the given list of lines

Source code in nomina/qif.py
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
def parse(self, lines: List[str], verbose: bool = False, debug: bool = False):
    """
    parse the given list of lines
    """
    current_record = {}
    record_type = None
    start_line = 1

    for line_num, line in enumerate(lines, 1):
        line = line.strip()
        if not line:
            continue
        if debug:
            print(f"{line_num}:{line}")
        if line.startswith("$"):
            self.currency = "USD"
        elif line.startswith("€"):
            self.currency = "EUR"
        if line.startswith("!Option:"):
            option = line[8:]
            self.options[option] = True
        elif line.startswith("!Clear:"):
            option = line[8:]
            self.options[option] = False
        elif line.startswith("!Type:") or line.startswith("!Account"):
            if current_record:
                self._add_record(
                    record_type, current_record, start_line, line_num - 1
                )
            if line.startswith("!Account"):
                record_type = "Account"
            else:
                record_type = line[6:]  # Text after !Type:
                pass
            current_record = {}
            start_line = line_num + 1
        elif line == "^":
            if current_record:
                self._add_record(record_type, current_record, start_line, line_num)
            current_record = {}
            start_line = line_num + 1

        elif line[0] in self.qif_fields:
            marker = line[0]
            qif_field = self.qif_fields[marker]
            qif_field.add_line_value_to_record(line, record_type, current_record)
        else:
            error = ErrorRecord(start_line=start_line, end_line=line_num, line=line)
            err_msg = f"parser can not handle line {line_num}: {line}"
            if verbose or debug:
                logging.error(err_msg)
            self.errors.append(error)

    if current_record:
        self._add_record(record_type, current_record, start_line, len(lines))

parse_file(qif_file, encoding='iso-8859-1', name=None, verbose=False, debug=False)

parse a qif file

Parameters:

Name Type Description Default
qif_file str

Path to the input QIF file.

required
encoding str

File encoding. Defaults to 'iso-8859-1'.

'iso-8859-1'
name str

name to set if None use the basename of the qif_file

None
verbose bool

if True give verbose output

False
debug bool

if True show debug output

False
Source code in nomina/qif.py
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
def parse_file(
    self,
    qif_file: str,
    encoding="iso-8859-1",
    name: str = None,
    verbose: bool = False,
    debug: bool = False,
):
    """
    parse a qif file

    Args:
        qif_file (str): Path to the input QIF file.
        encoding (str): File encoding. Defaults to 'iso-8859-1'.
        name (str): name to set if None use the basename of the qif_file
        verbose (bool): if True give verbose output
        debug (bool): if True show debug output
    """
    if name is None:
        name = os.path.basename(qif_file)
    self.name = name
    with open(qif_file, "r", encoding=encoding) as file:
        content = file.readlines()
    self.parse(content, verbose=verbose, debug=debug)

transaction_summary(transaction)

Helper function to provide a summary of a transaction.

Source code in nomina/qif.py
654
655
656
657
658
659
660
def transaction_summary(self, transaction):
    """Helper function to provide a summary of a transaction."""
    summary = []
    for field, value in vars(transaction).items():
        if field not in ["start_line", "end_line", "errors"] and value is not None:
            summary.append(f"{field}: {value}")
    return ", ".join(summary)

tx_for_record(t)

convert the transaction record

Source code in nomina/qif.py
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
def tx_for_record(self, t):
    """
    convert the transaction record
    """
    transaction = Transaction(start_line=t["_start_line"], end_line=t["_end_line"])
    # the S, E and $ lines are collected under the singular field names
    plural_keys = {
        "split_category": "split_categories",
        "split_memo": "split_memos",
        "split_amount": "split_amounts",
    }
    for key, value in t.items():
        if key.startswith("_"):
            continue
        setattr(transaction, plural_keys.get(key, key), value)
    transaction.normalize(date_formats=self.date_formats())
    return transaction

SplitCategory dataclass

a Quicken Interchange Format (QIF) Split target

Source code in nomina/qif.py
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
@dataclass
class SplitCategory:
    """
    a Quicken Interchange Format (QIF) Split target
    """

    markup: str  # the original QIF markup for the split category
    # parts of split
    category: Optional[str] = None
    account: Optional[str] = None
    split_class: Optional[str] = None
    # flags
    has_pipe: bool = False
    has_slash: bool = False

    def __post_init__(self):
        """
        parse my target string
        """
        self.has_pipe = "|" in self.markup
        self.has_slash = "/" in self.markup
        # qif holds the markup which still needs processing
        qif = self.markup

        pattern = r"\[(?P<account_name>[^\]]+)\]"

        # Search for the pattern in the split_category string
        match = re.search(pattern, self.markup)

        if match:
            # Extract the account name from the named group
            self.account = match.group("account_name")
            qif = qif.replace(f"[{self.account}]", "")
        else:
            self.account = None

        if self.has_pipe:
            qif = qif.replace("|", "")

        if self.has_slash:
            # Split by the first slash to separate category and class
            parts = qif.split("/", 1)
            if len(parts) > 1:
                # If there's a class after the slash, set it
                self.split_class = parts[1]
                qif = parts[0]
        if qif:
            self.category = qif

__post_init__()

parse my target string

Source code in nomina/qif.py
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def __post_init__(self):
    """
    parse my target string
    """
    self.has_pipe = "|" in self.markup
    self.has_slash = "/" in self.markup
    # qif holds the markup which still needs processing
    qif = self.markup

    pattern = r"\[(?P<account_name>[^\]]+)\]"

    # Search for the pattern in the split_category string
    match = re.search(pattern, self.markup)

    if match:
        # Extract the account name from the named group
        self.account = match.group("account_name")
        qif = qif.replace(f"[{self.account}]", "")
    else:
        self.account = None

    if self.has_pipe:
        qif = qif.replace("|", "")

    if self.has_slash:
        # Split by the first slash to separate category and class
        parts = qif.split("/", 1)
        if len(parts) > 1:
            # If there's a class after the slash, set it
            self.split_class = parts[1]
            qif = parts[0]
    if qif:
        self.category = qif

Transaction dataclass

Bases: ParseRecord

a single transaction

Source code in nomina/qif.py
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
@lod_storable
class Transaction(ParseRecord):
    """
    a single transaction
    """

    isodate: Optional[str] = None
    amount: Optional[str] = None
    name: Optional[str] = None  # Vorgang
    payee: Optional[str] = None
    memo: Optional[str] = None
    category: Optional[str] = None
    number: Optional[str] = None
    cleared: Optional[str] = None
    address: Optional[str] = None
    split_categories: List[SplitCategory] = field(default_factory=list)
    split_memos: List[str] = field(default_factory=list)
    split_amounts: List[str] = field(default_factory=list)
    account: Optional[Account] = None
    qif_class: Optional[QifClass] = None
    category: Optional[Category] = None

    def __post_init__(self):
        """
        extract details
        """
        self.amount_float: Optional[float] = None
        self.split_amounts_float: List[float] = []
        self.normalize()
        pass

    def normalize(self, date_formats: Optional[List[str]] = None):
        """
        Normalize the transaction data, converting string amounts to floats.

        Args:
            date_formats: the date formats to try, e.g. month first for !Option:MDY files
        """
        try:
            if self.isodate:
                self.isodate = DateUtils.parse_date(self.isodate, date_formats)
        except Exception as ex:
            self.errors["date"] = ex

        try:
            if self.amount:
                self.amount_float = self.parse_amount(self.amount)
        except Exception as ex:
            self.errors["amount"] = ex

        if self.name:
            if self.memo:
                self.memo = f"{self.name}:{self.memo}"
            else:
                self.memo = self.name

        self.split_amounts_float = []
        for i, amount in enumerate(self.split_amounts):
            try:
                self.split_amounts_float.append(self.parse_amount(amount))
            except Exception as ex:
                self.errors[f"split{i}"].append(ex)

    def parse_amount(self, amount_str: str) -> float:
        # Remove any currency symbols and whitespace
        cleaned_str = re.sub(r"[^\d,.-]", "", amount_str)
        # Replace comma with dot if comma is used as decimal separator
        if "," in cleaned_str and "." not in cleaned_str:
            cleaned_str = cleaned_str.replace(",", ".")
        elif "," in cleaned_str and "." in cleaned_str:
            cleaned_str = cleaned_str.replace(",", "")
        try:
            return float(cleaned_str)
        except ValueError:
            raise ValueError(f"Unable to parse amount: {amount_str}")

    def total_split_amount(self) -> float:
        """
        Calculate the total amount for split transactions.

        Returns:
            float: The sum of all split amounts.
        """
        return sum(self.split_amounts_float)

__post_init__()

extract details

Source code in nomina/qif.py
143
144
145
146
147
148
149
150
def __post_init__(self):
    """
    extract details
    """
    self.amount_float: Optional[float] = None
    self.split_amounts_float: List[float] = []
    self.normalize()
    pass

normalize(date_formats=None)

Normalize the transaction data, converting string amounts to floats.

Parameters:

Name Type Description Default
date_formats Optional[List[str]]

the date formats to try, e.g. month first for !Option:MDY files

None
Source code in nomina/qif.py
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def normalize(self, date_formats: Optional[List[str]] = None):
    """
    Normalize the transaction data, converting string amounts to floats.

    Args:
        date_formats: the date formats to try, e.g. month first for !Option:MDY files
    """
    try:
        if self.isodate:
            self.isodate = DateUtils.parse_date(self.isodate, date_formats)
    except Exception as ex:
        self.errors["date"] = ex

    try:
        if self.amount:
            self.amount_float = self.parse_amount(self.amount)
    except Exception as ex:
        self.errors["amount"] = ex

    if self.name:
        if self.memo:
            self.memo = f"{self.name}:{self.memo}"
        else:
            self.memo = self.name

    self.split_amounts_float = []
    for i, amount in enumerate(self.split_amounts):
        try:
            self.split_amounts_float.append(self.parse_amount(amount))
        except Exception as ex:
            self.errors[f"split{i}"].append(ex)

total_split_amount()

Calculate the total amount for split transactions.

Returns:

Name Type Description
float float

The sum of all split amounts.

Source code in nomina/qif.py
197
198
199
200
201
202
203
204
def total_split_amount(self) -> float:
    """
    Calculate the total amount for split transactions.

    Returns:
        float: The sum of all split amounts.
    """
    return sum(self.split_amounts_float)

qif_ledger

Created on 2024-10-04

@author: wf

QifToLedgerConverter

Bases: BaseToLedgerConverter

Convert Quicken QIF file to a Ledger Book.

Source code in nomina/qif_ledger.py
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
class QifToLedgerConverter(BaseToLedgerConverter):
    """
    Convert Quicken QIF file to a Ledger Book.
    """

    def __init__(self, debug: bool = False, vat_codes: Optional[VatCodes] = None):
        """
        Constructor for QIF to Ledger Book conversion.

        Args:
            debug (bool): Whether to enable debug logging.
            vat_codes (VatCodes): the VAT code map, None for the default map
        """
        super().__init__(from_format_acronym="QIF", debug=debug)
        self.qif_parser = SimpleQifParser()
        self.vat_codes = vat_codes if vat_codes is not None else VatCodes.of_yaml()

    def vat_code_for(
        self, qt: QifTransaction, split_class: Optional[str]
    ) -> Optional[str]:
        """
        get the VAT code for the given split class

        Args:
            qt(QifTransaction): the QIF transaction the split is for
            split_class(str): the class markup of the split e.g. _VATCode_N1_I

        Returns:
            Optional[str]: the VAT code with direction e.g. N1_I or None if the class is no VAT code
        """
        vat_code = None
        parsed = VatCodes.parse(split_class)
        if parsed:
            code, direction = parsed
            vat_code = f"{code}_{direction}"
            if self.vat_codes.lookup(code) is None:
                msg = f"unknown VAT code {code} at line {qt.start_line} {qt.isodate}"
                self.log.log("⚠️", "vat_code", msg)
        return vat_code

    def load(self, input_path: str):
        """
        Load the content from the input stream.
        """
        self.qif_parser.parse_file(input_path)
        self.set_source(self.qif_parser)
        return self.qif_parser

    def set_source(self, source: SimpleQifParser):
        self.qif_parser = source
        self.source = source

    def to_text(self) -> str:
        """
        Convert the target Ledger Book to YAML text.
        """
        return self.target.to_yaml()

    def create_account_lookup(self, ledger_book: Book):
        """
        Create a lookup of account names to Account objects from the QIF data.

        Args:
            ledger_book (Book): The ledger book to populate with accounts to use
            for lookup
        """
        # Create root accounts for classes and categories
        ledger_book.create_account(
            "Class", account_type="CLASS", description="root class"
        )
        ledger_book.create_account(
            "Category", account_type="CATEGORY", description="root category"
        )
        ledger_book.create_account(
            "Dangling", account_type="ERROR", description="dangling-error accounts"
        )

        # Create accounts from QIF data
        for account_name, account_data in self.qif_parser.accounts.items():
            parent_account_id = account_data.parent_account_id
            ledger_book.create_account(
                name=account_name,
                account_type=account_data.account_type,
                description=account_data.description,
                parent_account_id=parent_account_id,
            )

        # Create accounts for classes
        for class_name, class_data in self.qif_parser.classes.items():
            ledger_book.create_account(
                name=class_name,
                account_type="CLASS",
                description=class_data.description,
                parent_account_id="Class",
            )

        # Create accounts for categories
        for category_name, category_data in self.qif_parser.categories.items():
            ledger_book.create_account(
                name=category_name,
                account_type="CATEGORY",
                description=category_data.description,
                parent_account_id="Category",
            )

    def add_split(
        self,
        qt: QifTransaction,
        ledger_book: Book,
        amount: float,
        split_category: SplitCategory,
        memo: str,
        negative: bool = False,
    ) -> Split:
        """
        Helper method to add a split for a given split category

        Args:
            qt(QifTransaction): the QIF transaction the split is for
            ledger_book (Book): The ledger book containing accounts.
            amount (float): The amount for the split.
            split_category (SplitCategory): The split category.
            memo (str): The memo for the split.
            negative(bool): if True the amount should be negated

        Returns:
            Split: The created Split object.

        Raises:
            ValueError: If the target is not found in the ledger book.
        """
        qt_msg = str(qt)
        account = None
        # determine the account
        if split_category is None:
            return
        else:
            if split_category.account:
                account = ledger_book.lookup_account(split_category.account)
            elif split_category.category:
                # try regular account first
                account = ledger_book.lookup_account(split_category.category)
                # if that does not work fallback to trying lookup the category
                if not account:
                    account_name = f"Category:{split_category.category}"
                    account = ledger_book.lookup_account(account_name)

        if account is None:
            msg = f"invalid split category {split_category} for {qt_msg}"
            self.log.log("⚠️", "split", msg)
            account = ledger_book.lookup_account("Dangling")
            pass

        if amount is None:
            self.log.log(f"⚠️", "amount", f"no amount for {qt_msg}")
            amount = 0.0

        if negative:
            amount = -amount

        split = Split(amount=amount, account_id=account.account_id, memo=memo)
        return split

    def calc_splits(self, qt: Transaction, ledger_book: Book) -> List[Split]:
        """
        Create the debit and credit splits for a QIF transaction.

        Args:
            qt (Transaction): The QIF transaction object containing transaction details.
            ledger_book (Book): The ledger book containing accounts.

        Returns:
            List[Split]: A list of splits for the transaction.
        """
        splits = []
        transaction_account = ledger_book.lookup_account(qt.account.name)

        if transaction_account is None:
            qt_msg = str(qt)
            msg = f"unknown account {qt.account.name} in {qt_msg}"
            self.log.log("⚠️", "account", msg)
            return []

        # Handle split transactions
        if qt.split_categories and qt.split_amounts_float:
            # sum of cents, not of floats
            total_amount = round(qt.total_split_amount(), 2)

            # Create debit split for the main transaction account
            splits.append(
                Split(
                    amount=total_amount,
                    account_id=transaction_account.account_id,
                    memo=qt.memo,
                )
            )

            # Create credit splits for each split category
            for i in range(len(qt.split_categories)):
                split_category = qt.split_categories[i]
                split_amount = qt.split_amounts_float[i]
                split_memo = qt.split_memos[i] if i < len(qt.split_memos) else ""
                vat_code = self.vat_code_for(qt, split_category.split_class)
                if split_category.split_class and not vat_code:
                    split_memo = (
                        f"{split_memo}/{split_category.split_class}"
                        if split_memo
                        else split_category.split_class
                    )

                split = self.add_split(
                    qt,
                    ledger_book=ledger_book,
                    amount=-split_amount,
                    split_category=split_category,
                    memo=split_memo,
                )
                if split is not None:
                    split.vat_code = vat_code
                splits.append(split)
        else:
            # Handle non-split transactions
            debit_split = Split(
                amount=qt.amount_float,
                account_id=transaction_account.account_id,
                memo=qt.memo,
            )
            splits.append(debit_split)
            # Create credit split for the category account (source of funds)
            if not qt.category:
                category = "Dangling"
            else:
                category = qt.category
            split_category = SplitCategory(category)
            credit_split = self.add_split(
                qt,
                ledger_book,
                amount=qt.amount_float,
                split_category=split_category,
                memo=qt.memo,
                negative=True,
            )
            splits.append(credit_split)
        return splits

    def convert_to_target(self) -> Book:
        """
        Convert the QIF content to a Ledger Book.

        Returns:
            Book: A ledger book containing accounts and transactions.
        """
        # Create a new Book instance
        ledger_book = Book()
        ledger_book.name = self.source.name

        # Create accounts map from QIF data
        self.create_account_lookup(ledger_book)

        # Add transactions to the ledger book
        for transaction_id, qt in self.qif_parser.transactions.items():
            splits = self.calc_splits(qt, ledger_book)

            ledger_transaction = Transaction(
                isodate=qt.isodate,
                description=qt.memo,
                splits=splits,
                payee=qt.payee,
                memo=qt.memo,
            )

            ledger_book.transactions[transaction_id] = ledger_transaction
        self.target = ledger_book
        return ledger_book

__init__(debug=False, vat_codes=None)

Constructor for QIF to Ledger Book conversion.

Parameters:

Name Type Description Default
debug bool

Whether to enable debug logging.

False
vat_codes VatCodes

the VAT code map, None for the default map

None
Source code in nomina/qif_ledger.py
21
22
23
24
25
26
27
28
29
30
31
def __init__(self, debug: bool = False, vat_codes: Optional[VatCodes] = None):
    """
    Constructor for QIF to Ledger Book conversion.

    Args:
        debug (bool): Whether to enable debug logging.
        vat_codes (VatCodes): the VAT code map, None for the default map
    """
    super().__init__(from_format_acronym="QIF", debug=debug)
    self.qif_parser = SimpleQifParser()
    self.vat_codes = vat_codes if vat_codes is not None else VatCodes.of_yaml()

add_split(qt, ledger_book, amount, split_category, memo, negative=False)

Helper method to add a split for a given split category

Parameters:

Name Type Description Default
qt(QifTransaction)

the QIF transaction the split is for

required
ledger_book Book

The ledger book containing accounts.

required
amount float

The amount for the split.

required
split_category SplitCategory

The split category.

required
memo str

The memo for the split.

required
negative(bool)

if True the amount should be negated

required

Returns:

Name Type Description
Split Split

The created Split object.

Raises:

Type Description
ValueError

If the target is not found in the ledger book.

Source code in nomina/qif_ledger.py
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
def add_split(
    self,
    qt: QifTransaction,
    ledger_book: Book,
    amount: float,
    split_category: SplitCategory,
    memo: str,
    negative: bool = False,
) -> Split:
    """
    Helper method to add a split for a given split category

    Args:
        qt(QifTransaction): the QIF transaction the split is for
        ledger_book (Book): The ledger book containing accounts.
        amount (float): The amount for the split.
        split_category (SplitCategory): The split category.
        memo (str): The memo for the split.
        negative(bool): if True the amount should be negated

    Returns:
        Split: The created Split object.

    Raises:
        ValueError: If the target is not found in the ledger book.
    """
    qt_msg = str(qt)
    account = None
    # determine the account
    if split_category is None:
        return
    else:
        if split_category.account:
            account = ledger_book.lookup_account(split_category.account)
        elif split_category.category:
            # try regular account first
            account = ledger_book.lookup_account(split_category.category)
            # if that does not work fallback to trying lookup the category
            if not account:
                account_name = f"Category:{split_category.category}"
                account = ledger_book.lookup_account(account_name)

    if account is None:
        msg = f"invalid split category {split_category} for {qt_msg}"
        self.log.log("⚠️", "split", msg)
        account = ledger_book.lookup_account("Dangling")
        pass

    if amount is None:
        self.log.log(f"⚠️", "amount", f"no amount for {qt_msg}")
        amount = 0.0

    if negative:
        amount = -amount

    split = Split(amount=amount, account_id=account.account_id, memo=memo)
    return split

calc_splits(qt, ledger_book)

Create the debit and credit splits for a QIF transaction.

Parameters:

Name Type Description Default
qt Transaction

The QIF transaction object containing transaction details.

required
ledger_book Book

The ledger book containing accounts.

required

Returns:

Type Description
List[Split]

List[Split]: A list of splits for the transaction.

Source code in nomina/qif_ledger.py
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
def calc_splits(self, qt: Transaction, ledger_book: Book) -> List[Split]:
    """
    Create the debit and credit splits for a QIF transaction.

    Args:
        qt (Transaction): The QIF transaction object containing transaction details.
        ledger_book (Book): The ledger book containing accounts.

    Returns:
        List[Split]: A list of splits for the transaction.
    """
    splits = []
    transaction_account = ledger_book.lookup_account(qt.account.name)

    if transaction_account is None:
        qt_msg = str(qt)
        msg = f"unknown account {qt.account.name} in {qt_msg}"
        self.log.log("⚠️", "account", msg)
        return []

    # Handle split transactions
    if qt.split_categories and qt.split_amounts_float:
        # sum of cents, not of floats
        total_amount = round(qt.total_split_amount(), 2)

        # Create debit split for the main transaction account
        splits.append(
            Split(
                amount=total_amount,
                account_id=transaction_account.account_id,
                memo=qt.memo,
            )
        )

        # Create credit splits for each split category
        for i in range(len(qt.split_categories)):
            split_category = qt.split_categories[i]
            split_amount = qt.split_amounts_float[i]
            split_memo = qt.split_memos[i] if i < len(qt.split_memos) else ""
            vat_code = self.vat_code_for(qt, split_category.split_class)
            if split_category.split_class and not vat_code:
                split_memo = (
                    f"{split_memo}/{split_category.split_class}"
                    if split_memo
                    else split_category.split_class
                )

            split = self.add_split(
                qt,
                ledger_book=ledger_book,
                amount=-split_amount,
                split_category=split_category,
                memo=split_memo,
            )
            if split is not None:
                split.vat_code = vat_code
            splits.append(split)
    else:
        # Handle non-split transactions
        debit_split = Split(
            amount=qt.amount_float,
            account_id=transaction_account.account_id,
            memo=qt.memo,
        )
        splits.append(debit_split)
        # Create credit split for the category account (source of funds)
        if not qt.category:
            category = "Dangling"
        else:
            category = qt.category
        split_category = SplitCategory(category)
        credit_split = self.add_split(
            qt,
            ledger_book,
            amount=qt.amount_float,
            split_category=split_category,
            memo=qt.memo,
            negative=True,
        )
        splits.append(credit_split)
    return splits

convert_to_target()

Convert the QIF content to a Ledger Book.

Returns:

Name Type Description
Book Book

A ledger book containing accounts and transactions.

Source code in nomina/qif_ledger.py
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
def convert_to_target(self) -> Book:
    """
    Convert the QIF content to a Ledger Book.

    Returns:
        Book: A ledger book containing accounts and transactions.
    """
    # Create a new Book instance
    ledger_book = Book()
    ledger_book.name = self.source.name

    # Create accounts map from QIF data
    self.create_account_lookup(ledger_book)

    # Add transactions to the ledger book
    for transaction_id, qt in self.qif_parser.transactions.items():
        splits = self.calc_splits(qt, ledger_book)

        ledger_transaction = Transaction(
            isodate=qt.isodate,
            description=qt.memo,
            splits=splits,
            payee=qt.payee,
            memo=qt.memo,
        )

        ledger_book.transactions[transaction_id] = ledger_transaction
    self.target = ledger_book
    return ledger_book

create_account_lookup(ledger_book)

Create a lookup of account names to Account objects from the QIF data.

Parameters:

Name Type Description Default
ledger_book Book

The ledger book to populate with accounts to use

required
Source code in nomina/qif_ledger.py
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def create_account_lookup(self, ledger_book: Book):
    """
    Create a lookup of account names to Account objects from the QIF data.

    Args:
        ledger_book (Book): The ledger book to populate with accounts to use
        for lookup
    """
    # Create root accounts for classes and categories
    ledger_book.create_account(
        "Class", account_type="CLASS", description="root class"
    )
    ledger_book.create_account(
        "Category", account_type="CATEGORY", description="root category"
    )
    ledger_book.create_account(
        "Dangling", account_type="ERROR", description="dangling-error accounts"
    )

    # Create accounts from QIF data
    for account_name, account_data in self.qif_parser.accounts.items():
        parent_account_id = account_data.parent_account_id
        ledger_book.create_account(
            name=account_name,
            account_type=account_data.account_type,
            description=account_data.description,
            parent_account_id=parent_account_id,
        )

    # Create accounts for classes
    for class_name, class_data in self.qif_parser.classes.items():
        ledger_book.create_account(
            name=class_name,
            account_type="CLASS",
            description=class_data.description,
            parent_account_id="Class",
        )

    # Create accounts for categories
    for category_name, category_data in self.qif_parser.categories.items():
        ledger_book.create_account(
            name=category_name,
            account_type="CATEGORY",
            description=category_data.description,
            parent_account_id="Category",
        )

load(input_path)

Load the content from the input stream.

Source code in nomina/qif_ledger.py
56
57
58
59
60
61
62
def load(self, input_path: str):
    """
    Load the content from the input stream.
    """
    self.qif_parser.parse_file(input_path)
    self.set_source(self.qif_parser)
    return self.qif_parser

to_text()

Convert the target Ledger Book to YAML text.

Source code in nomina/qif_ledger.py
68
69
70
71
72
def to_text(self) -> str:
    """
    Convert the target Ledger Book to YAML text.
    """
    return self.target.to_yaml()

vat_code_for(qt, split_class)

get the VAT code for the given split class

Parameters:

Name Type Description Default
qt(QifTransaction)

the QIF transaction the split is for

required
split_class(str)

the class markup of the split e.g. _VATCode_N1_I

required

Returns:

Type Description
Optional[str]

Optional[str]: the VAT code with direction e.g. N1_I or None if the class is no VAT code

Source code in nomina/qif_ledger.py
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def vat_code_for(
    self, qt: QifTransaction, split_class: Optional[str]
) -> Optional[str]:
    """
    get the VAT code for the given split class

    Args:
        qt(QifTransaction): the QIF transaction the split is for
        split_class(str): the class markup of the split e.g. _VATCode_N1_I

    Returns:
        Optional[str]: the VAT code with direction e.g. N1_I or None if the class is no VAT code
    """
    vat_code = None
    parsed = VatCodes.parse(split_class)
    if parsed:
        code, direction = parsed
        vat_code = f"{code}_{direction}"
        if self.vat_codes.lookup(code) is None:
            msg = f"unknown VAT code {code} at line {qt.start_line} {qt.isodate}"
            self.log.log("⚠️", "vat_code", msg)
    return vat_code

stats

Created on 2024-10-06

@author: wf

Stats

Ledger statistics

Source code in nomina/stats.py
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
@lod_storable
class Stats:
    """
    Ledger statistics
    """

    accounts: int
    transactions: int
    start_date: Optional[str] = None
    end_date: Optional[str] = None
    classes: Optional[int] = None
    categories: Optional[int] = None
    errors: Optional[int] = None
    currencies: Dict[str, int] = field(default_factory=dict)
    other: Optional[Dict[str, Any]] = field(default_factory=dict)

    def show(self):
        print(f"# Accounts: {self.accounts}")
        print(f"# Transactions: {self.transactions}")
        print(f"Date Range: {self.start_date} to {self.end_date}")

        if self.classes is not None:
            print(f"# Classes: {self.classes}")

        if self.categories is not None:
            print(f"# Categories: {self.categories}")

        if self.errors is not None:
            print(f"# Errors: {self.errors}")

        if self.currencies:
            print(
                f"# Currencies: {', '.join(f'{currency}: {count}' for currency, count in self.currencies.items())}"
            )

        if self.other:
            print("Other Details:")
            for key, value in self.other.items():
                print(f"  {key}: {value}")

    def main_currency(self) -> Optional[str]:
        """
        Determine the main currency used in the ledger.

        Returns:
            Optional[str]: The currency with the highest count, or None if no currencies are present.
        """
        if not self.currencies:
            return None
        return max(self.currencies, key=self.currencies.get)

main_currency()

Determine the main currency used in the ledger.

Returns:

Type Description
Optional[str]

Optional[str]: The currency with the highest count, or None if no currencies are present.

Source code in nomina/stats.py
53
54
55
56
57
58
59
60
61
62
def main_currency(self) -> Optional[str]:
    """
    Determine the main currency used in the ledger.

    Returns:
        Optional[str]: The currency with the highest count, or None if no currencies are present.
    """
    if not self.currencies:
        return None
    return max(self.currencies, key=self.currencies.get)

vat_codes

Created on 2026-10-19

@author: wf

VAT codes as found in Finanzmanager Deluxe QIF exports, see issue #16

VatCode

a VAT code e.g. N1 with its rates

Source code in nomina/vat_codes.py
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
@lod_storable
class VatCode:
    """
    a VAT code e.g. N1 with its rates
    """

    code: str
    description: Optional[str] = ""
    rates: List[VatRate] = field(default_factory=list)

    def rate_for(self, isodate: Optional[str]) -> Optional[VatRate]:
        """
        get the rate valid at the given ISO date

        Args:
            isodate: the ISO date to check, None for the first rate

        Returns:
            Optional[VatRate]: the matching rate or None
        """
        vat_rate = None
        for candidate in self.rates:
            after_start = (
                isodate is None
                or candidate.valid_from is None
                or candidate.valid_from <= isodate
            )
            before_end = (
                isodate is None
                or candidate.valid_until is None
                or isodate <= candidate.valid_until
            )
            if vat_rate is None and after_start and before_end:
                vat_rate = candidate
        return vat_rate

rate_for(isodate)

get the rate valid at the given ISO date

Parameters:

Name Type Description Default
isodate Optional[str]

the ISO date to check, None for the first rate

required

Returns:

Type Description
Optional[VatRate]

Optional[VatRate]: the matching rate or None

Source code in nomina/vat_codes.py
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def rate_for(self, isodate: Optional[str]) -> Optional[VatRate]:
    """
    get the rate valid at the given ISO date

    Args:
        isodate: the ISO date to check, None for the first rate

    Returns:
        Optional[VatRate]: the matching rate or None
    """
    vat_rate = None
    for candidate in self.rates:
        after_start = (
            isodate is None
            or candidate.valid_from is None
            or candidate.valid_from <= isodate
        )
        before_end = (
            isodate is None
            or candidate.valid_until is None
            or isodate <= candidate.valid_until
        )
        if vat_rate is None and after_start and before_end:
            vat_rate = candidate
    return vat_rate

VatCodes

configurable map of VAT codes

Source code in nomina/vat_codes.py
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
@lod_storable
class VatCodes:
    """
    configurable map of VAT codes
    """

    name: Optional[str] = None
    codes: Dict[str, VatCode] = field(default_factory=dict)

    # QIF class markup e.g. _VATCode_N1_I - I: input tax, O: output VAT
    PATTERN: ClassVar[re.Pattern] = re.compile(
        r"^_VATCode_(?P<code>\w+?)_(?P<dir>[IO])$"
    )

    @classmethod
    def default_path(cls) -> str:
        """
        get the path of the default VAT code map

        Returns:
            str: the path of vat_codes.yaml in nomina_examples
        """
        path = os.path.join(
            os.path.dirname(__file__), "../nomina_examples/vat_codes.yaml"
        )
        path = os.path.abspath(path)
        return path

    @classmethod
    def of_yaml(cls, yaml_path: Optional[str] = None) -> "VatCodes":
        """
        load the VAT codes

        Args:
            yaml_path: the path of the yaml file, None for the default map

        Returns:
            VatCodes: the loaded VAT code map
        """
        if yaml_path is None:
            yaml_path = cls.default_path()
        vat_codes = cls.load_from_yaml_file(yaml_path)
        return vat_codes

    @classmethod
    def parse(cls, markup: Optional[str]) -> Optional[Tuple[str, str]]:
        """
        parse the given QIF class markup

        Args:
            markup: the class markup e.g. _VATCode_N1_I

        Returns:
            Optional[Tuple[str, str]]: code and direction or None if the markup is no VAT code
        """
        parsed = None
        if markup:
            match = cls.PATTERN.match(markup)
            if match:
                parsed = (match.group("code"), match.group("dir"))
        return parsed

    def lookup(self, code: str) -> Optional[VatCode]:
        """
        lookup the given VAT code

        Args:
            code: the code e.g. N1

        Returns:
            Optional[VatCode]: the VAT code or None if unknown
        """
        vat_code = self.codes.get(code)
        return vat_code

default_path() classmethod

get the path of the default VAT code map

Returns:

Name Type Description
str str

the path of vat_codes.yaml in nomina_examples

Source code in nomina/vat_codes.py
79
80
81
82
83
84
85
86
87
88
89
90
91
@classmethod
def default_path(cls) -> str:
    """
    get the path of the default VAT code map

    Returns:
        str: the path of vat_codes.yaml in nomina_examples
    """
    path = os.path.join(
        os.path.dirname(__file__), "../nomina_examples/vat_codes.yaml"
    )
    path = os.path.abspath(path)
    return path

lookup(code)

lookup the given VAT code

Parameters:

Name Type Description Default
code str

the code e.g. N1

required

Returns:

Type Description
Optional[VatCode]

Optional[VatCode]: the VAT code or None if unknown

Source code in nomina/vat_codes.py
127
128
129
130
131
132
133
134
135
136
137
138
def lookup(self, code: str) -> Optional[VatCode]:
    """
    lookup the given VAT code

    Args:
        code: the code e.g. N1

    Returns:
        Optional[VatCode]: the VAT code or None if unknown
    """
    vat_code = self.codes.get(code)
    return vat_code

of_yaml(yaml_path=None) classmethod

load the VAT codes

Parameters:

Name Type Description Default
yaml_path Optional[str]

the path of the yaml file, None for the default map

None

Returns:

Name Type Description
VatCodes VatCodes

the loaded VAT code map

Source code in nomina/vat_codes.py
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
@classmethod
def of_yaml(cls, yaml_path: Optional[str] = None) -> "VatCodes":
    """
    load the VAT codes

    Args:
        yaml_path: the path of the yaml file, None for the default map

    Returns:
        VatCodes: the loaded VAT code map
    """
    if yaml_path is None:
        yaml_path = cls.default_path()
    vat_codes = cls.load_from_yaml_file(yaml_path)
    return vat_codes

parse(markup) classmethod

parse the given QIF class markup

Parameters:

Name Type Description Default
markup Optional[str]

the class markup e.g. _VATCode_N1_I

required

Returns:

Type Description
Optional[Tuple[str, str]]

Optional[Tuple[str, str]]: code and direction or None if the markup is no VAT code

Source code in nomina/vat_codes.py
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
@classmethod
def parse(cls, markup: Optional[str]) -> Optional[Tuple[str, str]]:
    """
    parse the given QIF class markup

    Args:
        markup: the class markup e.g. _VATCode_N1_I

    Returns:
        Optional[Tuple[str, str]]: code and direction or None if the markup is no VAT code
    """
    parsed = None
    if markup:
        match = cls.PATTERN.match(markup)
        if match:
            parsed = (match.group("code"), match.group("dir"))
    return parsed

VatRate

a VAT rate with its validity period

Source code in nomina/vat_codes.py
17
18
19
20
21
22
23
24
25
@lod_storable
class VatRate:
    """
    a VAT rate with its validity period
    """

    rate: Optional[float] = None  # percent, None if the split carries the tax only
    valid_from: Optional[str] = None  # ISO date
    valid_until: Optional[str] = None  # ISO date

version

Created on 2024-10-06 @author: wf

Version dataclass

Bases: object

Version handling for MoneyBrowser

Source code in nomina/version.py
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
@dataclass
class Version(object):
    """
    Version handling for MoneyBrowser
    """

    name = "pynomina"
    version = nomina.__version__
    date = "2024-10-06"
    updated = "2026-10-19"
    description = "Personal finance tool"
    authors = "Wolfgang Fahl"

    doc_url = "https://wiki.bitplan.com/index.php/Pynomina"
    chat_url = "https://github.com/WolfgangFahl/pynomina/discussions/"
    cm_url = "https://github.com/WolfgangFahl/pynomina"

    license = f"""Copyright 2024-2025 contributors. All rights reserved.

  Licensed under the Apache License 2.0
  http://www.apache.org/licenses/LICENSE-2.0

  Distributed on an "AS IS" basis without warranties
  or conditions of any kind, either express or implied."""
    longDescription = f"""{name} version {version}
{description}

  Created by {authors} on {date} last updated {updated}"""

webserver

Created on 2024-10-06

@author: wf

NominaSolution

Bases: InputWebSolution

the Nomina solution

Source code in nomina/webserver.py
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
class NominaSolution(InputWebSolution):
    """
    the Nomina solution
    """

    def __init__(self, webserver: NominaWebServer, client: Client):
        """
        Initialize the solution

        Calls the constructor of the base solution
        Args:
            webserver (NiceScadWebServer): The webserver instance associated with this context.
            client (Client): The client instance this context is associated with.
        """
        super().__init__(webserver, client)  # Call to the superclass constructor
        self.book_view = None
        self.root_path = self.webserver.root_path
        self.input = "example.beancount"

    def prepare_ui(self):
        """
        prepare the user interface
        """
        InputWebSolution.prepare_ui(self)
        # try styling for account view
        ui.add_head_html(
            """<style>
.amount-negative {
    color: red;
}
.amount-positive {
    color: blue;
}
</style>
""",
            shared=True,
        )

    async def read_and_optionally_render(self, input_str, with_render: bool = False):
        """
        Reads the given input and optionally renders the given input

        Args:
            input_str (str): The input string representing a URL or local file.
            with_render(bool): if True also render
        """
        if self.book_view is not None:
            await self.book_view.read_and_optionally_render(input_str, with_render)

    def configure_menu(self):
        """
        configure additional non-standard menu entries
        """
        self.tool_button(
            tooltip="reload",
            icon="refresh",
            handler=self.reload_file,
        )
        if self.is_local:
            self.tool_button(
                tooltip="open",
                icon="file_open",
                handler=self.open_file,
            )

    def show_ui(self):
        """
        show the ui
        """
        with self.content_div:
            self.book_view = BookView(self)
            self.book_view.setup_ui()

    async def home(self):
        """
        Home screen
        """
        await self.setup_content_div(self.show_ui)
        if self.args.input:
            await self.read_and_optionally_render(self.args.input)

__init__(webserver, client)

Initialize the solution

Calls the constructor of the base solution Args: webserver (NiceScadWebServer): The webserver instance associated with this context. client (Client): The client instance this context is associated with.

Source code in nomina/webserver.py
67
68
69
70
71
72
73
74
75
76
77
78
79
def __init__(self, webserver: NominaWebServer, client: Client):
    """
    Initialize the solution

    Calls the constructor of the base solution
    Args:
        webserver (NiceScadWebServer): The webserver instance associated with this context.
        client (Client): The client instance this context is associated with.
    """
    super().__init__(webserver, client)  # Call to the superclass constructor
    self.book_view = None
    self.root_path = self.webserver.root_path
    self.input = "example.beancount"

configure_menu()

configure additional non-standard menu entries

Source code in nomina/webserver.py
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def configure_menu(self):
    """
    configure additional non-standard menu entries
    """
    self.tool_button(
        tooltip="reload",
        icon="refresh",
        handler=self.reload_file,
    )
    if self.is_local:
        self.tool_button(
            tooltip="open",
            icon="file_open",
            handler=self.open_file,
        )

home() async

Home screen

Source code in nomina/webserver.py
135
136
137
138
139
140
141
async def home(self):
    """
    Home screen
    """
    await self.setup_content_div(self.show_ui)
    if self.args.input:
        await self.read_and_optionally_render(self.args.input)

prepare_ui()

prepare the user interface

Source code in nomina/webserver.py
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
    def prepare_ui(self):
        """
        prepare the user interface
        """
        InputWebSolution.prepare_ui(self)
        # try styling for account view
        ui.add_head_html(
            """<style>
.amount-negative {
    color: red;
}
.amount-positive {
    color: blue;
}
</style>
""",
            shared=True,
        )

read_and_optionally_render(input_str, with_render=False) async

Reads the given input and optionally renders the given input

Parameters:

Name Type Description Default
input_str str

The input string representing a URL or local file.

required
with_render(bool)

if True also render

required
Source code in nomina/webserver.py
100
101
102
103
104
105
106
107
108
109
async def read_and_optionally_render(self, input_str, with_render: bool = False):
    """
    Reads the given input and optionally renders the given input

    Args:
        input_str (str): The input string representing a URL or local file.
        with_render(bool): if True also render
    """
    if self.book_view is not None:
        await self.book_view.read_and_optionally_render(input_str, with_render)

show_ui()

show the ui

Source code in nomina/webserver.py
127
128
129
130
131
132
133
def show_ui(self):
    """
    show the ui
    """
    with self.content_div:
        self.book_view = BookView(self)
        self.book_view.setup_ui()

NominaWebServer

Bases: InputWebserver

Nomina Webserver

Source code in nomina/webserver.py
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
class NominaWebServer(InputWebserver):
    """
    Nomina Webserver
    """

    @classmethod
    def get_config(cls) -> WebserverConfig:
        copy_right = "(c)2024-2025 Wolfgang Fahl"
        config = WebserverConfig(
            copy_right=copy_right,
            version=Version(),
            default_port=9849,
            short_name="nomina",
        )
        server_config = WebserverConfig.get(config)
        server_config.solution_class = NominaSolution
        return server_config

    def __init__(self):
        """Constructs all the necessary attributes for the WebServer object."""
        InputWebserver.__init__(self, config=NominaWebServer.get_config())

    def configure_run(self):
        """
        configure things before the server rung
        """
        root_path = (
            self.args.root_path
            if self.args.root_path
            else NominaWebServer.examples_path()
        )
        self.root_path = os.path.abspath(root_path)
        self.allowed_urls = [
            self.examples_path(),
            self.root_path,
        ]

    @classmethod
    def examples_path(cls) -> str:
        # the root directory (default: examples)
        path = os.path.join(os.path.dirname(__file__), "../nomina_examples")
        path = os.path.abspath(path)
        return path

__init__()

Constructs all the necessary attributes for the WebServer object.

Source code in nomina/webserver.py
35
36
37
def __init__(self):
    """Constructs all the necessary attributes for the WebServer object."""
    InputWebserver.__init__(self, config=NominaWebServer.get_config())

configure_run()

configure things before the server rung

Source code in nomina/webserver.py
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def configure_run(self):
    """
    configure things before the server rung
    """
    root_path = (
        self.args.root_path
        if self.args.root_path
        else NominaWebServer.examples_path()
    )
    self.root_path = os.path.abspath(root_path)
    self.allowed_urls = [
        self.examples_path(),
        self.root_path,
    ]