Files
@ 9b63d898af70
Branch filter:
Location: NPO-Accounting/conservancy_beancount/conservancy_beancount/data.py
9b63d898af70
7.2 KiB
text/x-python
data: Add Metadata class.
As I start writing more link-checking hooks, I want a common place to
write link-parsing code. This new class will be that place.
As I start writing more link-checking hooks, I want a common place to
write link-parsing code. This new class will be that place.
1 2 3 4 5 6 7 8 9 10 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 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 | """Enhanced Beancount data structures for Conservancy
The classes in this module are interface-compatible with Beancount's core data
structures, and provide additional business logic that we want to use
throughout Conservancy tools.
"""
# Copyright © 2020 Brett Smith
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
import collections
from beancount.core import account as bc_account
from typing import (
Iterable,
Iterator,
MutableMapping,
Optional,
Sequence,
)
from .beancount_types import (
MetaKey,
MetaValue,
Posting as BasePosting,
Transaction,
)
LINK_METADATA = frozenset([
'approval',
'check',
'contract',
'invoice',
'purchase-order',
'receipt',
'statement',
])
class Account(str):
"""Account name string
This is a string that names an account, like Accrued:AccountsPayable
or Income:Donations. This class provides additional methods for common
account name parsing and queries.
"""
SEP = bc_account.sep
def is_income(self) -> bool:
return self.is_under('Income:', 'UnearnedIncome:') is not None
def is_real_asset(self) -> bool:
return bool(
self.is_under('Assets:')
and not self.is_under('Assets:PrepaidExpenses', 'Assets:PrepaidVacation')
)
def is_under(self, *acct_seq: str) -> Optional[str]:
"""Return a match if this account is "under" a part of the hierarchy
Pass in any number of account name strings as arguments. If this
account is under one of those strings in the account hierarchy, the
first matching string will be returned. Otherwise, None is returned.
You can use the return value of this method as a boolean if you don't
care which account string is matched.
An account is considered to be under itself:
Account('Expenses:Tax').is_under('Expenses:Tax') # returns 'Expenses:Tax'
To do a "strictly under" search, end your search strings with colons:
Account('Expenses:Tax').is_under('Expenses:Tax:') # returns None
Account('Expenses:Tax').is_under('Expenses:') # returns 'Expenses:'
This method does check that all the account boundaries match:
Account('Expenses:Tax').is_under('Exp') # returns None
"""
for prefix in acct_seq:
if self.startswith(prefix) and (
prefix.endswith(self.SEP)
or self == prefix
or self[len(prefix)] == self.SEP
):
return prefix
return None
class Metadata(MutableMapping[MetaKey, MetaValue]):
"""Transaction or posting metadata
This class wraps a Beancount metadata dictionary with additional methods
for common parsing and query tasks.
"""
def __init__(self, source: MutableMapping[MetaKey, MetaValue]) -> None:
self.meta = source
def __iter__(self) -> Iterator[MetaKey]:
return iter(self.meta)
def __len__(self) -> int:
return len(self.meta)
def __getitem__(self, key: MetaKey) -> MetaValue:
return self.meta[key]
def __setitem__(self, key: MetaKey, value: MetaValue) -> None:
self.meta[key] = value
def __delitem__(self, key: MetaKey) -> None:
del self.meta[key]
def get_links(self, key: MetaKey) -> Sequence[str]:
try:
value = self.meta[key]
except KeyError:
return ()
if isinstance(value, str):
return value.split()
else:
raise TypeError("{} metadata is a {}, not str".format(
key, type(value).__name__,
))
class PostingMeta(Metadata):
"""Combined access to posting metadata with its parent transaction metadata
This lets you access posting metadata through a single dict-like object.
If you try to look up metadata that doesn't exist on the posting, it will
look for the value in the parent transaction metadata instead.
You can set and delete metadata as well. Changes only affect the metadata
of the posting, never the transaction. Changes are propagated to the
underlying Beancount data structures.
Functionally, you can think of this as identical to:
collections.ChainMap(post.meta, txn.meta)
Under the hood, this class does a little extra work to avoid creating
posting metadata if it doesn't have to.
"""
def __init__(self,
txn: Transaction,
index: int,
post: Optional[BasePosting]=None,
) -> None:
if post is None:
post = txn.postings[index]
self.txn = txn
self.index = index
self.post = post
if post.meta is None:
self.meta = self.txn.meta
else:
self.meta = collections.ChainMap(post.meta, txn.meta)
def __setitem__(self, key: MetaKey, value: MetaValue) -> None:
if self.post.meta is None:
self.post = self.post._replace(meta={key: value})
self.txn.postings[self.index] = self.post
# mypy complains that self.post.meta could be None, but we know
# from two lines up that it's not.
self.meta = collections.ChainMap(self.post.meta, self.txn.meta) # type:ignore[arg-type]
else:
super().__setitem__(key, value)
def __delitem__(self, key: MetaKey) -> None:
if self.post.meta is None:
raise KeyError(key)
else:
super().__delitem__(key)
class Posting(BasePosting):
"""Enhanced Posting objects
This class is a subclass of Beancount's native Posting class where
specific fields are replaced with enhanced versions:
* The `account` field is an Account object
* The `meta` field is a PostingMeta object
"""
account: Account
# mypy correctly complains that our MutableMapping is not compatible
# with Beancount's meta type declaration of Optional[Dict]. IMO
# Beancount's type declaration is a smidge too specific: I think its type
# declaration should also use MutableMapping, because it would be very
# unusual for code to specifically require a Dict over that.
# If it did, this declaration would pass without issue.
meta: Metadata # type:ignore[assignment]
def iter_postings(txn: Transaction) -> Iterator[Posting]:
"""Yield an enhanced Posting object for every posting in the transaction"""
for index, source in enumerate(txn.postings):
yield Posting(
Account(source.account),
*source[1:5],
# see rationale above about Posting.meta
PostingMeta(txn, index, source), # type:ignore[arg-type]
)
|