simplebooks 0.1.0__py3-none-any.whl

simplebooks/__init__.py

@@ -0,0 +1,51 @@
+from .models import (
+    Account,
+    AccountType,
+    Currency,
+    Customer,
+    Entry,
+    EntryType,
+    Identity,
+    Ledger,
+    Transaction,
+    Vendor,
+)
+import sqloquent.tools
+
+__version__ = '0.1.0'
+
+def set_connection_info(db_file_path: str):
+    """Set the connection info for all models to use the specified
+        sqlite3 database file path.
+    """
+    Account.connection_info = db_file_path
+    Currency.connection_info = db_file_path
+    Customer.connection_info = db_file_path
+    Entry.connection_info = db_file_path
+    Identity.connection_info = db_file_path
+    Ledger.connection_info = db_file_path
+    Transaction.connection_info = db_file_path
+    Vendor.connection_info = db_file_path
+
+def publish_migrations(migration_folder_path: str):
+    """Writes migration files for the models."""
+    sqloquent.tools.publish_migrations(migration_folder_path)
+    models = [
+        Account,
+        Currency,
+        Customer,
+        Entry,
+        Identity,
+        Ledger,
+        Transaction,
+        Vendor,
+    ]
+    for model in models:
+        name = model.__name__
+        m = sqloquent.tools.make_migration_from_model(model)
+        with open(f'{migration_folder_path}/create_{name}.py', 'w') as f:
+            f.write(m)
+
+def automigrate(migration_folder_path: str, db_file_path: str):
+    """Executes the sqloquent automigrate tool."""
+    sqloquent.tools.automigrate(migration_folder_path, db_file_path)

simplebooks/asyncql/Account.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+from sqloquent.asyncql import (
+    AsyncSqlModel, AsyncRelatedModel, AsyncRelatedCollection,
+)
+from .AccountType import AccountType
+from .Entry import Entry
+from .EntryType import EntryType
+import packify
+
+
+class Account(AsyncSqlModel):
+    connection_info: str = ''
+    table: str = 'accounts'
+    id_column: str = 'id'
+    columns: tuple[str] = (
+        'id', 'name', 'type', 'ledger_id', 'parent_id', 'code',
+        'category', 'details'
+    )
+    id: str
+    name: str
+    type: str
+    ledger_id: str
+    parent_id: str
+    code: str|None
+    category: str|None
+    details: bytes|None
+    ledger: AsyncRelatedModel
+    parent: AsyncRelatedModel
+    children: AsyncRelatedCollection
+    entries: AsyncRelatedCollection
+
+    # override automatic property
+    @property
+    def type(self) -> AccountType:
+        """The AccountType of the Account."""
+        return AccountType(self.data['type'])
+    @type.setter
+    def type(self, val: AccountType):
+        if type(val) is AccountType:
+            self.data['type'] = val.value
+
+    # override automatic property
+    @property
+    def details(self) -> packify.SerializableType:
+        """A packify.SerializableType stored in the database as a blob."""
+        return packify.unpack(self.data.get('details', None) or b'n\x00\x00\x00\x00')
+    @details.setter
+    def details(self, val: packify.SerializableType):
+        if isinstance(val, packify.SerializableType):
+            self.data['details'] = packify.pack(val)
+
+    @staticmethod
+    def _encode(data: dict|None) -> dict|None:
+        if type(data) is not dict:
+            return data
+        if type(data.get('type', None)) is AccountType:
+            data['type'] = data['type'].value
+        return data
+
+    @classmethod
+    async def insert(cls, data: dict) -> Account | None:
+        """Ensure data is encoded before inserting."""
+        result = await super().insert(cls._encode(data))
+        return result
+
+    async def balance(self, include_sub_accounts: bool = True) -> int:
+        """Tally all entries for this account. Includes the balances of
+            all sub-accounts if include_sub_accounts is True.
+        """
+        totals = {
+            EntryType.CREDIT: 0,
+            EntryType.DEBIT: 0,
+            'subaccounts': 0,
+        }
+        async for entries in self.entries().query().chunk(500):
+            entry: Entry
+            for entry in entries:
+                totals[entry.type] += entry.amount
+
+        if include_sub_accounts:
+            for acct in self.children:
+                acct: Account
+                totals['subaccounts'] += await acct.balance(include_sub_accounts=True)
+
+        if self.type in (
+            AccountType.ASSET, AccountType.DEBIT_BALANCE,
+            AccountType.CONTRA_LIABILITY, AccountType.CONTRA_EQUITY,
+        ):
+            return totals[EntryType.DEBIT] - totals[EntryType.CREDIT] + totals['subaccounts']
+
+        return totals[EntryType.CREDIT] - totals[EntryType.DEBIT] + totals['subaccounts']

simplebooks/asyncql/AccountType.py

@@ -0,0 +1,16 @@
+from enum import Enum
+
+
+class AccountType(Enum):
+    """Enum of valid Account types: DEBIT_BALANCE, ASSET, CONTRA_ASSET,
+        CREDIT_BALANCE, LIABILITY, EQUITY, CONTRA_LIABILITY,
+        CONTRA_EQUITY.
+    """
+    DEBIT_BALANCE = 'd'
+    ASSET = 'a'
+    CONTRA_ASSET = '-a'
+    CREDIT_BALANCE = 'c'
+    LIABILITY = 'l'
+    EQUITY = 'e'
+    CONTRA_LIABILITY = '-l'
+    CONTRA_EQUITY = '-e'

simplebooks/asyncql/Currency.py

@@ -0,0 +1,67 @@
+from decimal import Decimal
+from sqloquent.asyncql import AsyncSqlModel
+
+
+class Currency(AsyncSqlModel):
+    connection_info: str = ''
+    table: str = 'currencies'
+    id_column: str = 'id'
+    columns: tuple[str] = (
+        'id', 'name', 'prefix_symbol', 'postfix_symbol',
+        'fx_symbol', 'unit_divisions', 'base', 'details'
+    )
+    id: str
+    name: str
+    prefix_symbol: str|None
+    postfix_symbol: str|None
+    fx_symbol: str|None
+    unit_divisions: int
+    base: int|None
+    details: str|None
+
+    def to_decimal(self, amount: int) -> Decimal:
+        """Convert the amount into a Decimal representation."""
+        base = self.base or 10
+        return Decimal(amount) / Decimal(base**self.unit_divisions)
+
+    def get_units(self, amount: int) -> tuple[int,]:
+        """Get the full units and subunits. The number of subunit
+            figures will be equal to unit_divisions; e.g. if base=10
+            and unit_divisions=2, get_units(200) will return (2, 0, 0);
+            if base=60 and unit_divisions=2, get_units(200) will return
+            (0, 3, 20).
+        """
+        def get_subunits(amount, base, unit_divisions):
+            units_and_change = divmod(amount, base ** unit_divisions)
+            if unit_divisions > 1:
+                units_and_change = (units_and_change[0], *get_subunits(units_and_change[1], base, unit_divisions-1))
+            return units_and_change
+        base = self.base or 10
+        unit_divisions = self.unit_divisions
+        return get_subunits(amount, base, unit_divisions)
+
+    def format(self, amount: int, *, decimal_places: int = 2,
+               use_prefix: bool = True, use_postfix: bool = False,
+               use_fx_symbol: bool = False) -> str:
+        """Format an amount using the correct number of decimal_places."""
+        amount: str = str(self.to_decimal(amount))
+        if '.' not in amount:
+            amount += '.'
+        digits = amount.split('.')[1]
+
+        while len(digits) < decimal_places:
+            digits += '0'
+
+        digits = digits[:decimal_places]
+        amount = f"{amount.split('.')[0]}.{digits}"
+
+        if self.postfix_symbol and use_postfix:
+            return f"{amount}{self.postfix_symbol}"
+
+        if self.fx_symbol and use_fx_symbol:
+            return f"{amount} {self.fx_symbol}"
+
+        if self.prefix_symbol and use_prefix:
+            return f"{self.prefix_symbol}{amount}"
+
+        return amount

simplebooks/asyncql/Customer.py

@@ -0,0 +1,23 @@
+from sqloquent.asyncql import AsyncSqlModel
+import packify
+
+
+class Customer(AsyncSqlModel):
+    connection_info: str = ''
+    table: str = 'customers'
+    id_column: str = 'id'
+    columns: tuple[str] = ('id', 'name', 'code', 'details')
+    id: str
+    name: str
+    code: str|None
+    details: str|None
+
+    # override automatic property
+    @property
+    def details(self) -> packify.SerializableType:
+        """A packify.SerializableType stored in the database as a blob."""
+        return packify.unpack(self.data.get('details', None) or b'n\x00\x00\x00\x00')
+    @details.setter
+    def details(self, val: packify.SerializableType):
+        if isinstance(val, packify.SerializableType):
+            self.data['details'] = packify.pack(val)

simplebooks/asyncql/Entry.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+from sqloquent.asyncql import (
+    AsyncSqlModel, AsyncRelatedModel, AsyncRelatedCollection, AsyncQueryBuilderProtocol
+)
+from .EntryType import EntryType
+import packify
+
+
+class Entry(AsyncSqlModel):
+    connection_info: str = ''
+    table: str = 'entries'
+    id_column: str = 'id'
+    columns: tuple[str] = ('id', 'type', 'amount', 'nonce', 'account_id', 'details')
+    id: str
+    type: str
+    amount: int
+    nonce: bytes
+    account_id: str
+    details: bytes
+    account: AsyncRelatedModel
+    transactions: AsyncRelatedCollection
+
+    def __hash__(self) -> int:
+        data = self.encode_value(self._encode(self.data))
+        return hash(bytes(data, 'utf-8'))
+
+    # override automatic properties
+    @property
+    def type(self) -> EntryType:
+        """The EntryType of the Entry."""
+        return EntryType(self.data['type'])
+    @type.setter
+    def type(self, val: EntryType):
+        if type(val) is not EntryType:
+            return
+        self.data['type'] = val.value
+
+    @property
+    def details(self) -> packify.SerializableType:
+        """A packify.SerializableType stored in the database as a blob."""
+        return packify.unpack(self.data.get('details', b'n\x00\x00\x00\x00'))
+    @details.setter
+    def details(self, val: packify.SerializableType):
+        self.data['details'] = packify.pack(val)
+
+    @staticmethod
+    def _encode(data: dict|None) -> dict|None:
+        if type(data) is not dict:
+            return data
+        if type(data.get('type', None)) is EntryType:
+            data['type'] = data['type'].value
+        if type(data.get('details', {})) is not bytes:
+            data['details'] = packify.pack(data.get('details', None))
+        return data
+
+    @staticmethod
+    def _parse(data: dict|None) -> dict|None:
+        if type(data) is dict and type(data['amount']) is str:
+            data['amount'] = int(data['amount'])
+        return data
+
+    @staticmethod
+    def parse(models: Entry|list[Entry]) -> Entry|list[Entry]:
+        if type(models) is list:
+            for model in models:
+                model.data = Entry._parse(model.data)
+        else:
+            models.data = Entry._parse(models.data)
+        return models
+
+    @classmethod
+    async def insert(cls, data: dict) -> Entry | None:
+        """Ensure data is encoded before inserting."""
+        result = await super().insert(cls._encode(data))
+        return result
+
+    @classmethod
+    async def insert_many(cls, items: list[dict]) -> int:
+        """Ensure data is encoded before inserting."""
+        items = [Entry._encode(data) for data in list]
+        return await super().insert_many(items)
+
+    @classmethod
+    def query(cls, conditions: dict = None) -> AsyncQueryBuilderProtocol:
+        """Ensure conditions are encoded properly before querying."""
+        return super().query(cls._encode(conditions))

simplebooks/asyncql/EntryType.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class EntryType(Enum):
+    """Enum of valid Entry types: CREDIT and DEBIT."""
+    CREDIT = 'c'
+    DEBIT = 'd'

simplebooks/asyncql/Identity.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+from .Account import Account, AccountType
+from .Ledger import Ledger
+from sqloquent.asyncql import AsyncSqlModel, AsyncRelatedCollection
+
+
+class Identity(AsyncSqlModel):
+    connection_info: str = ''
+    table: str = 'identities'
+    id_column: str = 'id'
+    columns: tuple[str] = ('id', 'name', 'details', 'pubkey', 'seed', 'secret_details')
+    columns_excluded_from_hash: tuple[str] = ('seed', 'secret_details')
+    id: str
+    name: str
+    details: bytes
+    pubkey: bytes|None
+    seed: bytes|None
+    secret_details: bytes|None
+    ledgers: AsyncRelatedCollection
+
+    def public(self) -> dict:
+        """Return the public data for cloning the Identity."""
+        return {
+            k:v for k,v in self.data.items()
+            if k not in self.columns_excluded_from_hash
+        }

simplebooks/asyncql/Ledger.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+from .Account import Account, AccountType
+from sqloquent.asyncql import AsyncSqlModel, AsyncRelatedModel, AsyncRelatedCollection
+
+
+class Ledger(AsyncSqlModel):
+    connection_info: str = ''
+    table: str = 'ledgers'
+    id_column: str = 'id'
+    columns: tuple[str] = ('id', 'name', 'identity_id', 'currency_id')
+    id: str
+    name: str
+    identity_id: str
+    currency_id: str
+    owner: AsyncRelatedModel
+    currency: AsyncRelatedModel
+    accounts: AsyncRelatedCollection
+    transactions: AsyncRelatedCollection
+
+    async def balances(self, reload: bool = False) -> dict[str, tuple[int, AccountType]]:
+        """Return a dict mapping account ids to their balances. Accounts
+            with sub-accounts will not include the sub-account balances;
+            the sub-account balances will be returned separately.
+        """
+        balances = {}
+        if reload:
+            await self.accounts().reload()
+        for account in self.accounts:
+            balances[account.id] = (await account.balance(False), account.type)
+        return balances
+
+    def setup_basic_accounts(self) -> list[Account]:
+        """Creates and returns a list of 3 unsaved Accounts covering the
+            3 basic categories: Asset, Liability, Equity.
+        """
+        asset = Account({
+            'name': f'General Asset ({self.owner.name})',
+            'type': AccountType.ASSET,
+            'ledger_id': self.id,
+            'code': '1xx'
+        })
+        liability = Account({
+            'name': f'General Liability ({self.owner.name})',
+            'type': AccountType.LIABILITY,
+            'ledger_id': self.id,
+            'code': '2xx'
+        })
+        equity = Account({
+            'name': f'General Equity ({self.owner.name})',
+            'type': AccountType.EQUITY,
+            'ledger_id': self.id,
+            'code': '28x'
+        })
+        return [asset, liability, equity]

simplebooks/asyncql/Transaction.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+from hashlib import sha256
+from sqloquent.asyncql import AsyncSqlModel, AsyncRelatedCollection
+from sqloquent.errors import vert, tert
+from .Account import Account, AccountType
+from .Entry import Entry, EntryType
+from .Identity import Identity
+import packify
+
+
+class Transaction(AsyncSqlModel):
+    connection_info: str = ''
+    table: str = 'transactions'
+    id_column: str = 'id'
+    columns: tuple[str] = ('id', 'entry_ids', 'ledger_ids', 'timestamp', 'details')
+    id: str
+    entry_ids: str
+    ledger_ids: str
+    timestamp: str
+    details: bytes
+    entries: AsyncRelatedCollection
+    ledgers: AsyncRelatedCollection
+
+    # override automatic properties
+    @property
+    def details(self) -> dict[str, bytes]:
+        """A packify.SerializableType stored in the database as a blob."""
+        return packify.unpack(self.data.get('details', b'd\x00\x00\x00\x00'))
+    @details.setter
+    def details(self, val: dict[str, bytes]):
+        if type(val) is not dict:
+            return
+        if not all([type(k) is str and type(v) is bytes for k, v in val.items()]):
+            return
+        self.data['details'] = packify.pack(val)
+
+    @classmethod
+    def _encode(cls, data: dict|None) -> dict|None:
+        """Encode values for saving."""
+        if type(data) is not dict:
+            return None
+        if type(data.get('details', {})) is dict:
+            data['details'] = packify.pack(data.get('details', {}))
+        return data
+
+    @classmethod
+    async def prepare(cls, entries: list[Entry], timestamp: str,
+                      details: packify.SerializableType = None,
+                      reload: bool = False) -> Transaction:
+        """Prepare a transaction. Raises TypeError for invalid arguments.
+            Raises ValueError if the entries do not balance for each
+            ledger; if a required auth script is missing; or if any of
+            the entries is contained within an existing Transaction.
+            Entries and Transaction will have IDs generated but will not
+            be persisted to the database and must be saved separately.
+        """
+        tert(type(entries) is list and all([type(e) is Entry for e in entries]),
+            'entries must be list[Entry]')
+        tert(type(timestamp) is str, 'timestamp must be str')
+
+        ledgers = set()
+        for entry in entries:
+            entry.id = entry.id if entry.id else entry.generate_id()
+            if reload:
+                await entry.account().reload()
+            vert(await Transaction.query().contains('entry_ids', entry.id).count() == 0,
+                 f"entry {entry.id} is already contained within a Transaction")
+            ledgers.add(entry.account.ledger_id)
+
+        txn = cls({
+            'entry_ids': ",".join(sorted([
+                e.id if e.id else e.generate_id()
+                for e in entries
+            ])),
+            'ledger_ids': ",".join(sorted(list(ledgers))),
+            'timestamp': timestamp,
+        })
+        txn.details = details
+        txn.entries = entries
+        assert await txn.validate(reload), \
+            'transaction validation failed'
+        txn.id = txn.generate_id()
+        return txn
+
+    async def validate(self, reload: bool = False) -> bool:
+        """Determines if a Transaction is valid using the rules of accounting.
+            Raises TypeError for invalid arguments. Raises ValueError if the
+            entries do not balance for each ledger; or if any of the entries is
+            contained within an existing Transaction. If reload is set to True,
+            entries and accounts will be reloaded from the database.
+        """
+        if reload:
+            await self.entries().reload()
+
+        # first check that all ledgers balance
+        ledgers = {}
+        entry: Entry
+        for entry in self.entries:
+            if reload:
+                await entry.account().reload()
+            if entry.account.ledger_id not in ledgers:
+                ledgers[entry.account.ledger_id] = {'Dr': 0, 'Cr': 0}
+            if entry.type in (EntryType.CREDIT, EntryType.CREDIT.value):
+                ledgers[entry.account.ledger_id]['Cr'] += entry.amount
+            else:
+                ledgers[entry.account.ledger_id]['Dr'] += entry.amount
+
+        for ledger_id, balances in ledgers.items():
+            vert(balances['Cr'] == balances['Dr'],
+                f"ledger {ledger_id} unbalanced: {balances['Cr']} Cr != {balances['Dr']} Dr")
+
+        return True
+
+    async def save(self, reload: bool = False) -> Transaction:
+        """Validate the transaction, save the entries, then save the
+            transaction.
+        """
+        assert await self.validate(reload), 'cannot save an invalid Transaction'
+        for e in self.entries:
+            await e.save()
+        return await super().save()

simplebooks/asyncql/Vendor.py

@@ -0,0 +1,23 @@
+from sqloquent.asyncql import AsyncSqlModel
+import packify
+
+
+class Vendor(AsyncSqlModel):
+    connection_info: str = ''
+    table: str = 'vendors'
+    id_column: str = 'id'
+    columns: tuple[str] = ('id', 'name', 'code', 'details')
+    id: str
+    name: str
+    code: str|None
+    details: str|None
+
+    # override automatic property
+    @property
+    def details(self) -> packify.SerializableType:
+        """A packify.SerializableType stored in the database as a blob."""
+        return packify.unpack(self.data.get('details', None) or b'n\x00\x00\x00\x00')
+    @details.setter
+    def details(self, val: packify.SerializableType):
+        if isinstance(val, packify.SerializableType):
+            self.data['details'] = packify.pack(val)

simplebooks/asyncql/__init__.py

@@ -0,0 +1,53 @@
+from .Account import Account, AccountType
+from .Currency import Currency
+from .Customer import Customer
+from .Entry import Entry, EntryType
+from .Identity import Identity
+from .Ledger import Ledger
+from .Transaction import Transaction
+from .Vendor import Vendor
+from sqloquent.asyncql import (
+    async_contains, async_within, async_has_many, async_belongs_to,
+)
+
+
+Identity.ledgers = async_has_many(Identity, Ledger, 'identity_id')
+Ledger.owner = async_belongs_to(Ledger, Identity, 'identity_id')
+
+Ledger.currency = async_belongs_to(Ledger, Currency, 'currency_id')
+
+Ledger.accounts = async_has_many(Ledger, Account, 'ledger_id')
+Account.ledger = async_belongs_to(Account, Ledger, 'ledger_id')
+
+Account.children = async_has_many(Account, Account, 'parent_id')
+Account.parent = async_belongs_to(Account, Account, 'parent_id')
+
+Account.entries = async_has_many(Account, Entry, 'account_id')
+Entry.account = async_belongs_to(Entry, Account, 'account_id')
+
+Entry.transactions = async_within(Entry, Transaction, 'entry_ids')
+Transaction.entries = async_contains(Transaction, Entry, 'entry_ids')
+
+Transaction.ledgers = async_contains(Transaction, Ledger, 'ledger_ids')
+Ledger.transactions = async_within(Ledger, Transaction, 'ledger_ids')
+
+
+def set_connection_info(db_file_path: str):
+    """Set the connection info for all models to use the specified
+        sqlite3 database file path.
+    """
+    Account.connection_info = db_file_path
+    Currency.connection_info = db_file_path
+    Customer.connection_info = db_file_path
+    Entry.connection_info = db_file_path
+    Identity.connection_info = db_file_path
+    Ledger.connection_info = db_file_path
+    Transaction.connection_info = db_file_path
+    Vendor.connection_info = db_file_path
+
+
+# no longer needed
+del async_contains
+del async_belongs_to
+del async_within
+del async_has_many