) -> Optional[MetaValueEnum]:

        """Return self[key], or a default fallback if that doesn't exist.

        default_key is another key to look up, *not* a default value to return.

        This helps ensure you always get a standard value.

        """

        try:

            return self[key]

        except KeyError:

            if default_key is None:

                return None

            else:

                return self[default_key]

### HOOK SUBCLASSES

class _PostingHook(TransactionHook, metaclass=abc.ABCMeta):

    TXN_DATE_RANGE: _GenericRange = _GenericRange(DEFAULT_START_DATE, DEFAULT_STOP_DATE)

    def __init_subclass__(cls) -> None:

        cls.HOOK_GROUPS = cls.HOOK_GROUPS.union(['posting'])

    def _run_on_txn(self, txn: Transaction) -> bool:

    def _run_on_post(self, txn: Transaction, post: data.Posting) -> bool:

        return True

    def run(self, txn: Transaction) -> errormod.Iter:

        if self._run_on_txn(txn):

            for post in data.iter_postings(txn):

                if self._run_on_post(txn, post):

                    yield from self.post_run(txn, post)

    @abc.abstractmethod

    def post_run(self, txn: Transaction, post: data.Posting) -> errormod.Iter: ...

class _NormalizePostingMetadataHook(_PostingHook):

    """Base class to normalize posting metadata from an enum."""

    # This class provides basic functionality to filter postings, normalize

    # metadata values, and set default values.

    METADATA_KEY: MetaKey

    VALUES_ENUM: MetadataEnum

    def __init_subclass__(cls) -> None:

        super().__init_subclass__()

        cls.METADATA_KEY = cls.VALUES_ENUM.key

    Transaction,

)

from typing import (

    Pattern,

)

class MetaEntity(core.TransactionHook):

    METADATA_KEY = 'entity'

    HOOK_GROUPS = frozenset(['posting', 'metadata', METADATA_KEY])

    # alnum is the set of characters we always accept in entity metadata:

    # letters and digits, minus the Latin 1 supplement (i.e., Roman letters

    # with diacritics: áÁàÀâÂåÅäÄãà çÇ ðÐ ñÑ øØ ß etc.)

    # See the tests for specific cases.

    alnum = r'\p{Letter}\p{Digit}--\p{Block=Latin_1_Supplement}'

    # A regexp that would be reasonably stricter would be:

    #   f'^[{alnum}][.{alnum}]*(?:-[.{alnum}])*$'

    # However, current producers fail that regexp in a few different ways.

    # See the tests for specific cases.

    ENTITY_RE: Pattern[str] = regex.compile(f'^[{alnum}][-.{alnum}]*$', regex.VERSION1)

    del alnum

    def run(self, txn: Transaction) -> errormod.Iter:

        txn_entity = txn.meta.get(self.METADATA_KEY, txn.payee)

        if txn_entity is None:

            txn_entity_ok = None

        elif isinstance(txn_entity, str):

            txn_entity_ok = bool(self.ENTITY_RE.match(txn_entity))

        else:

            txn_entity_ok = False

        if txn_entity_ok is False:

            yield errormod.InvalidMetadataError(txn, self.METADATA_KEY, txn_entity)

        for post in data.iter_postings(txn):

            if not post.account.is_under(

                    'Assets:Receivable',

                    'Expenses',

                    'Income',

                    'Liabilities:Payable',

            ):

                continue

            entity = post.meta.get(self.METADATA_KEY)

            if entity is None:

                yield errormod.InvalidMetadataError(txn, self.METADATA_KEY, entity, post)

            elif entity is txn_entity:

                pass

            elif not self.ENTITY_RE.match(entity):

                yield errormod.InvalidMetadataError(txn, self.METADATA_KEY, entity, post)

import yaml

import yaml.error

from . import core

from .. import config as configmod

from .. import data

from .. import errors as errormod

from ..beancount_types import (

    MetaValueEnum,

    Transaction,

)

from typing import (

    Any,

    Dict,

    NoReturn,

    Optional,

    Set,

)

class MetaProject(core._NormalizePostingMetadataHook):

    DEFAULT_PROJECT = 'Conservancy'

    PROJECT_DATA_PATH = Path('Projects', 'project-data.yml')

    VALUES_ENUM = core.MetadataEnum('project', {DEFAULT_PROJECT})

    def __init__(self, config: configmod.Config, source_path: Path=PROJECT_DATA_PATH) -> None:

        repo_path = config.repository_path()

        if repo_path is None:

            self._config_error("no repository configured")

        project_data_path = repo_path / source_path

        source = {'filename': str(project_data_path)}

        try:

            with project_data_path.open() as yaml_file:

                project_data: Dict[str, Dict[str, Any]] = yaml.safe_load(yaml_file)

            names: Set[MetaValueEnum] = {self.DEFAULT_PROJECT}

            aliases: Dict[MetaValueEnum, MetaValueEnum] = {}

            for key, params in project_data.items():

                name = params.get('accountName', key)

                names.add(name)

                human_name = params.get('humanName', name)

                if name != human_name:

                    aliases[human_name] = name

                if name != key:

                    aliases[key] = name

        except AttributeError:

            self._config_error("loaded YAML data not in project-data format", project_data_path)

        except OSError as error:

            self._config_error(error.strerror, project_data_path)

        except yaml.error.YAMLError as error:

            self._config_error(error.args[0] or "YAML load error", project_data_path)

        else:

            self.VALUES_ENUM = core.MetadataEnum(self.METADATA_KEY, names, aliases)

    def _config_error(self, msg: str, filename: Optional[Path]=None) -> NoReturn:

        source = {}

        if filename is not None:

            source['filename'] = str(filename)

        raise errormod.ConfigurationError(

            "cannot load project data: " + msg,

            source=source,

        )

        if post.account.is_under('Liabilities'):

            return not post.account.is_credit_card()

        else:

            return post.account.is_under(

                'Assets:Receivable',

                'Expenses',

                'Income',

            ) is not None

    def _default_value(self, txn: Transaction, post: data.Posting) -> MetaValueEnum:

        if post.account.is_under(

                'Expenses:Payroll',

                'Liabilities:Payable:Vacation',

        ):

            return self.DEFAULT_PROJECT

        else:

            raise errormod.InvalidMetadataError(txn, self.METADATA_KEY, None, post)

    ('Assets:Bank:Checking', False),

    ('Assets:Cash', False),

    ('Assets:Receivable:Accounts', True),

    ('Assets:Receivable:Loans', True),

    ('Equity:OpeningBalances', False),

    ('Expenses:General', True),

    ('Income:Donations', True),

    ('Liabilities:CreditCard', False),

    ('Liabilities:Payable:Accounts', True),

    ('Liabilities:Payable:Vacation', True),

    ('Liabilities:UnearnedIncome:Donations', False),

])

def test_which_accounts_required_on(hook, account, required):

    txn = testutil.Transaction(postings=[

        ('Assets:Checking', -25),

        (account, 25),

    ])

    errors = list(hook.run(txn))

    if not required:

        assert not errors

    else:

        assert errors

        assert any(error.message == "{} missing entity".format(account)

                   for error in errors)

#

# 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 pytest

from . import testutil

from conservancy_beancount.plugin import meta_invoice

REQUIRED_ACCOUNTS = {

    'Assets:Receivable:Accounts',

    'Assets:Receivable:Loans',

    'Liabilities:Payable:Accounts',

    'Liabilities:Payable:Vacation',

}

NON_REQUIRED_ACCOUNTS = {

    'Assets:Cash',

    'Expenses:Other',

    'Income:Other',

    'Liabilities:CreditCard',

}

TEST_KEY = 'invoice'

MISSING_MSG = f'{{}} missing {TEST_KEY}'.format

WRONG_TYPE_MSG = f'{{}} has wrong type of {TEST_KEY}: expected str but is a {{}}'.format

@pytest.fixture(scope='module')

def hook():

    config = testutil.TestConfig()

    return meta_invoice.MetaInvoice(config)

@pytest.mark.parametrize('acct1,acct2,value', testutil.combine_values(

    REQUIRED_ACCOUNTS,

    NON_REQUIRED_ACCOUNTS,

    testutil.LINK_METADATA_STRINGS,

))

def test_valid_values_on_postings(hook, acct1, acct2, value):

    txn = testutil.Transaction(postings=[

        (acct2, -25),

        (acct1, 25, {TEST_KEY: value}),

))

def test_bad_type_values_on_transaction(hook, acct1, acct2, value):

    txn = testutil.Transaction(**{TEST_KEY: value}, postings=[

        (acct2, -25),

        (acct1, 25),

    ])

    expected = {

        MISSING_MSG(acct1),

        WRONG_TYPE_MSG(acct1, type(value).__name__),

    }

    actual = {error.message for error in hook.run(txn)}

    assert actual == expected

@pytest.mark.parametrize('acct1,acct2', testutil.combine_values(

    REQUIRED_ACCOUNTS,

    NON_REQUIRED_ACCOUNTS,

))

def test_missing_invoice(hook, acct1, acct2):

    txn = testutil.Transaction(postings=[

        (acct2, -25),

        (acct1, 25),

    ])

    actual = {error.message for error in hook.run(txn)}

    assert actual == {"{} missing {}".format(acct1, TEST_KEY)}

    }

    check(hook, expected, txn_meta=meta)

def test_paid_accts_not_checked(hook):

    txn = testutil.Transaction(postings=[

        (TEST_ACCT, 250),

        (OTHER_ACCT, -250),

    ])

    assert not list(hook.run(txn))

@pytest.mark.parametrize('account', [

    'Assets:Bank:Checking',

    'Assets:Cash',

    'Assets:Receivable:Accounts',

    'Equity:OpeningBalance',

    'Expenses:BankingFees',

    'Income:Donations',

    'Liabilities:CreditCard',

    'Liabilities:Payable:Vacation',

    'Liabilities:UnearnedIncome:Donations',

])

def test_does_not_apply_to_other_accounts(hook, account):

    meta = seed_meta()

    check(hook, None, account, post_meta=meta)

    ])

    actual = {error.message for error in hook.run(txn)}

    assert actual == {INVALID_MSG(acct, src_value)}

def test_required_for_assets_paypal(hook):

    acct = 'Assets:PayPal'

    txn = testutil.Transaction(postings=[

        ('Income:Donations', -35),

        (acct, 35),

    ])

    actual = {error.message for error in hook.run(txn)}

    assert actual == {f"{acct} missing {TEST_KEY}"}

@pytest.mark.parametrize('txn_id,inv_id', testutil.combine_values(

    VALID_TXN_IDS,

    VALID_INVOICE_IDS,

))

def test_invoice_payment_transaction_ok(hook, txn_id, inv_id):

    txn = testutil.Transaction(**{TEST_KEY: txn_id}, postings=[

        ('Assets:Receivable:Accounts', -100, {TEST_KEY: inv_id}),

        ('Assets:PayPal', 97),

        ('Expenses:BankingFees', 3),

    ])

    assert not list(hook.run(txn))

def test_valid_values_on_transactions(hook, src_value, set_value):

    txn = testutil.Transaction(**{TEST_KEY: src_value}, postings=[

        ('Assets:Cash', -25),

        ('Expenses:General', 25),

    ])

    errors = list(hook.run(txn))

    assert not errors

    testutil.check_post_meta(txn, None, {TEST_KEY: set_value})

@pytest.mark.parametrize('src_value', INVALID_VALUES)

def test_invalid_values_on_transactions(hook, src_value):

    txn = testutil.Transaction(**{TEST_KEY: src_value}, postings=[

        ('Assets:Cash', -25),

        ('Expenses:General', 25),

    ])

    errors = list(hook.run(txn))

    assert errors

    testutil.check_post_meta(txn, None, None)

@pytest.mark.parametrize('account,required', [

    ('Assets:Cash', False),

    ('Assets:Receivable:Accounts', True),

    ('Assets:Receivable:Loans', True),

    ('Equity:OpeningBalance', False),

    ('Expenses:General', True),

    ('Income:Donations', True),

    ('Liabilities:CreditCard', False),

    ('Liabilities:Payable:Accounts', True),

    # We do want a "project" for Lia:Pay:Vacation but it has a default value

    ('Liabilities:Payable:Vacation', False),

    ('Liabilities:UnearnedIncome:Donations', True),

])

def test_which_accounts_required_on(hook, account, required):

    txn = testutil.Transaction(postings=[

        ('Assets:Checking', 25),

        (account, 25),

    ])

    errors = list(hook.run(txn))

    assert required == any(errors)

@pytest.mark.parametrize('account', [

    'Expenses:Payroll:Salary',

    'Expenses:Payroll:Tax',

    'Liabilities:Payable:Vacation',

])

def test_default_values(hook, account):

    txn = testutil.Transaction(postings=[

        ('Assets:Checking', -25),

        ('Liabilities:Payable:Vacation', -25),

    ])

    errors = list(hook.run(txn))

    assert not errors

    expect_meta = {TEST_KEY: DEFAULT_VALUE} if required else None

    testutil.check_post_meta(txn, expect_meta, expect_meta)

@pytest.mark.parametrize('repo_path', [

    None,

    '..',

])

def test_missing_project_data(repo_path):

    config = testutil.TestConfig(repo_path=repo_path)

    with pytest.raises(errormod.ConfigurationError):

        meta_project.MetaProject(config)

@pytest.mark.parametrize('repo_path_s,data_path_s', [

    ('repository', 'Projects/project-list.yml'),

    ('..', 'LICENSE.txt'),

])

def test_invalid_project_data(repo_path_s, data_path_s):

    config = testutil.TestConfig(repo_path=repo_path_s)

    with pytest.raises(errormod.ConfigurationError):

        meta_project.MetaProject(config, Path(data_path_s))

    ('Assets:Checking', PostType.DEBIT, 'check-id'),

    ('Assets:Savings', PostType.BOTH, None),

    ('Liabilities:CreditCard', PostType.CREDIT, None),

    ('Liabilities:CreditCard', PostType.DEBIT, 'invoice'),

]]

ACCOUNTS_WITH_LINK_FALLBACK = [acct for acct in ACCOUNTS

                               if acct.fallback_meta and acct.fallback_meta != 'check-id']

ACCOUNTS_WITH_CHECK_ID_FALLBACK = [acct for acct in ACCOUNTS

                                   if acct.fallback_meta == 'check-id']

ACCOUNTS_WITHOUT_FALLBACKS = [acct for acct in ACCOUNTS if not acct.fallback_meta]

KNOWN_FALLBACKS = {acct.fallback_meta for acct in ACCOUNTS if acct.fallback_meta}

# These are mostly fill-in values.

# We don't need to run every test on every value for these, just enough to

# convince ourselves the hook never reports errors against these accounts.

# Making this a iterator rather than a sequence means testutil.combine_values

# doesn't require the decorated test to go over every value, which in turn

# trims unnecessary test time.

NOT_REQUIRED_ACCOUNTS = itertools.cycle([

    # Only paypal-id is required for PayPal transactions

    'Assets:PayPal',

    'Assets:Prepaid:Expenses',

    'Assets:Receivable:Accounts',

    'Expenses:Other',

    'Income:Other',

    'Liabilities:Payable:Accounts',

    'Liabilities:UnearnedIncome:Donations',

])

CHECK_IDS = (decimal.Decimal(n) for n in itertools.count(1))

def BAD_CHECK_IDS():

    # Valid check-id values are positive integers

    yield decimal.Decimal(0)

    yield -next(CHECK_IDS)

    yield next(CHECK_IDS) * decimal.Decimal('1.1')

BAD_CHECK_IDS = BAD_CHECK_IDS()

def check(hook, test_acct, other_acct, expected, *,

          txn_meta={}, post_meta={}, check_type=PostType.BOTH, min_amt=0):

    check_type &= test_acct.required_types

    assert check_type, "tried to test a non-applicable account"

    if check_type == PostType.BOTH:

        check(hook, test_acct, other_acct, expected,

              txn_meta=txn_meta, post_meta=post_meta, check_type=PostType.CREDIT)

        check_type = PostType.DEBIT

    amount = decimal.Decimal('{:.02f}'.format(min_amt + random.random() * 100))

    if check_type == PostType.DEBIT:

    ACCOUNTS_WITHOUT_FALLBACKS,

    NOT_REQUIRED_ACCOUNTS,

    KNOWN_FALLBACKS,

    testutil.LINK_METADATA_STRINGS,

))

def test_fallback_not_accepted_on_other_accounts(hook, test_acct, other_acct, key, value):

    check(hook, test_acct, other_acct, {test_acct.missing_message()},

          post_meta={key: value})

@pytest.mark.parametrize('test_acct,other_acct,value', testutil.combine_values(

    ACCOUNTS_WITH_LINK_FALLBACK,

    NOT_REQUIRED_ACCOUNTS,

    testutil.LINK_METADATA_STRINGS,

))

def test_fallback_on_zero_amount_postings(hook, test_acct, other_acct, value):

    # Unfortunately it does happen that we get donations that go 100% to

    # banking fees, and our importer writes a zero-amount posting to the

    # Assets account.

    txn = testutil.Transaction(postings=[

        ('Income:Donations', '-.1'),

        ('Expenses:BankingFees', '.1'),

        (test_acct.name, 0, {test_acct.fallback_meta: value}),

    ])

    assert not list(hook.run(txn))

))

def test_paid_invoices_not_checked(hook, invoice, other_acct):

    txn = testutil.Transaction(postings=[

        (TEST_ACCT, -250, {'invoice': invoice}),

        (other_acct, 250),

    ])

    assert not list(hook.run(txn))

@pytest.mark.parametrize('account', [

    'Assets:Bank:Checking',

    'Assets:Cash',

    'Equity:OpeningBalance',

    'Expenses:BankingFees',

    'Liabilities:CreditCard',

    'Liabilities:Payable:Accounts',

])

def test_does_not_apply_to_other_accounts(hook, account):

    meta = seed_meta()

    check(hook, None, account, 'Expenses:Other', post_meta=meta)

def test_configuration_error_without_rt():

    config = testutil.TestConfig()

    with pytest.raises(errormod.ConfigurationError):

        meta_receivable_documentation.MetaReceivableDocumentation(config)