Reference

python_ccb.ClearCheckBook

This class connects to ClearCheckBook

Parameters:
  • username (str) – Username used to login to ClearCheckBook

  • password (str) – Password used to login to ClearCheckBook

  • app_ref (str) – Application tracking ID. Defaults to None.

delete_transaction(self, transaction)

Delete a transaction

Parameters:
  • transaction (transaction) – Transaction to delete.

Source code in python_ccb/__init__.py
def delete_transaction(self, transaction):
    """Delete a transaction

    Args:
        transaction (transaction): Transaction to delete.
    """
    response = self._session.delete('transaction', data={'id': transaction.id})
    response.raise_for_status()
    if not response.json()['status']:
        raise RuntimeError(response.json()['error_msg'])

edit_split(self, transaction, split_list)

Edit a transaction and its splited transactions

Parameters:
  • transaction (transaction) – Transaction to edit.

  • split_list (list) – Transaction list containing the splitted transactions

Returns:
  • List of Transaction

Source code in python_ccb/__init__.py
def edit_split(self, transaction, split_list):
    """Edit a transaction and its splited transactions

    Args:
        transaction (transaction): Transaction to edit.
        split_list (list): Transaction list containing the splitted transactions

    Returns:
        List of `Transaction`
    """

    return self._manage_split('edit', transaction, split_list)

edit_transaction(self, transaction, from_account=None, to_account=None, is_split=False, split_amounts=[], split_categories=[], split_descriptions=[])

Edit a transaction

Parameters:
  • transaction (transaction) – Transaction to edit.

  • from_account (Account) – If this transaction is converted into a transfer, this is the account you're transferring from.

  • to_account (Account) – If this transaction is converted into a transfer, this is the account you're transferring to.

  • is_split (bool) – If the transaction is being split, set this to True.

  • split_amount (list) – List of float values for each split child.

  • split_categories (list) – List of categories for each split child.

  • split_descriptions (list) – List of descriptions for each split child.

Returns:
  • List of Transaction

Exceptions:
  • ValueError – if transaction doesn't have a valid id

Source code in python_ccb/__init__.py
def edit_transaction(self, transaction, from_account=None, to_account=None,
                     is_split=False, split_amounts=[], split_categories=[],
                     split_descriptions=[]):
    """Edit a transaction

    Args:
        transaction (transaction): Transaction to edit.
        from_account (Account): If this transaction is converted into a transfer,
            this is the account you're transferring from.
        to_account (Account): If this transaction is converted into a transfer,
            this is the account you're transferring to.
        is_split (bool): If the transaction is being split, set this to `True`.
        split_amount (list): List of float values for each split child.
        split_categories (list): List of categories for each split child.
        split_descriptions (list): List of descriptions for each split child.

    Returns:
        List of `Transaction`

    Raises:
        ValueError: if transaction doesn't have a valid `id`
    """

    if not transaction.id:
        raise ValueError(f'transaction has no id')
    data = {'id': transaction.id}
    return self._manage_transaction('put', transaction, data, from_account,
                                    to_account, is_split, split_amounts,
                                    split_categories, split_descriptions)

get_account(self, name=None, account_id=None)

Get an account.

Parameters:
  • name (str) – name of the account

  • account_id (int) – id of the account

Returns:
  • Account

Warning

ClearCheckBook lets you add two accounts with the same name. In this case API behavior is unpredictable.

Source code in python_ccb/__init__.py
def get_account(self, name=None, account_id=None):
    """Get an account.

    Args:
        name (str): name of the account
        account_id (int): id of the account

    Returns:
        `Account`

    Warning:
        ClearCheckBook lets you add two accounts with the same name. In this case
        API behavior is unpredictable.
    """

    if account_id == 0:
        return NO_ACCOUNT
    elif name:
        for account in self.get_accounts():
            if account.name == name:
                return account
        else:
            raise ValueError(f'no account found with name {name}')
    else:
        response = self._session.get('account', params={'id': account_id})
        response.raise_for_status()
        if not response.json()['status']:
            raise RuntimeError(response.json()['error_msg'])
        account_data = response.json()['data']
        return Account.from_api(account_data,
                                self.get_currency(account_data['currency_code']))

get_accounts(self, is_overview=False, all=True)

Get all accounts.

Parameters:
  • is_overview (bool) – True to return only the accounts with a balance. False to return every account. Defaults to False

  • all (bool) – True to return all accounts and NO_ACCOUNT if it exists.

Returns:
  • A list of Account

Source code in python_ccb/__init__.py
def get_accounts(self, is_overview=False, all=True):
    """Get all accounts.

    Args:
        is_overview (bool): `True` to return only the accounts with a balance. `False`
            to return every account. Defaults to `False`
        all (bool): `True` to return all accounts and `NO_ACCOUNT` if it exists.

    Returns:
        A list of `Account`

    """
    response = self._session.get('accounts', params={'is_overview': is_overview,
                                                     'all': all})
    response.raise_for_status()
    if not response.json()['status']:
        raise RuntimeError(response.json()['error_msg'])
    return [Account.from_api(account_data,
                             self.get_currency(account_data['currency_code']))
            for account_data in response.json()['data']]

get_categories(self)

Get all categories

Returns:
  • List of Castegory

Source code in python_ccb/__init__.py
def get_categories(self):
    """Get all categories

    Returns:
        List of `Castegory`
    """

    response = self._session.get('categories')
    response.raise_for_status()
    if not response.json()['status']:
        raise RuntimeError(response.json()['error_msg'])
    categories = []
    for category_data in response.json()['data']:
        category = Category(**category_data)
        if category.parent:
            for category_parent in categories:
                if category_parent.id == category.parent:
                    category.parent = category_parent
                    break
        categories.append(category)
    return categories

get_category(self, name=None, category_id=None)

Get a category

Parameters:
  • name (str) – name of the category

  • category_id (int) – id of the category

Returns:
  • Category

Warning

ClearCheckBook lets you add two categories with the same name. In this case API behavior is unpredictable.

Source code in python_ccb/__init__.py
def get_category(self, name=None, category_id=None):
    """Get a category

    Args:
        name (str): name of the category
        category_id (int): id of the category

    Returns:
        `Category`

    Warning:
        ClearCheckBook lets you add two categories with the same name. In this case
        API behavior is unpredictable.
     """

    if category_id == 0:
        return NO_CATEGORY
    for category in self.get_categories():
        if category.name == name or category.id == category_id:
            return category
    else:
        raise ValueError(f'no account found with name {name} or id {category_id}')

get_currencies(self)

Get all currencies

Returns:
  • List of Currency

Source code in python_ccb/__init__.py
@lru_cache(maxsize=16)
def get_currencies(self):
    """Get all currencies

    Returns:
        List of `Currency`
     """

    response = self._session.get('currencies')
    response.raise_for_status()
    if not response.json()['status']:
        raise RuntimeError(response.json()['error_msg'])
    return [Currency(**currency) for currency in response.json()['data']]

get_currency(self, code=None, id=None)

Get a currency

Parameters:
  • code (str) – The three digit currency code (eg: USD)

  • category_id (int) – id of the currency

Returns:
  • Currency

Source code in python_ccb/__init__.py
@lru_cache(maxsize=16)
def get_currency(self, code=None, id=None):
    """Get a currency

    Args:
        code (str): The three digit currency code (eg: USD)
        category_id (int): id of the currency

    Returns:
        `Currency`
     """

    if not id and not code:
        raise TypeError('get_currency() takes either the id or code arguments')
    response = self._session.get('currency', params={'code': code, 'id': id})
    response.raise_for_status()
    if not response.json()['status']:
        raise RuntimeError(response.json()['error_msg'])
    return Currency(**response.json()['data'])

get_transaction(self, id)

Get a transaction.

Parameters:
  • id (int) – ID of the transaction

Returns:
  • Transaction

Source code in python_ccb/__init__.py
def get_transaction(self, id):
    """Get a transaction.

    Args:
        id (int): ID of the transaction

    Returns:
        `Transaction`
    """

    response = self._session.get('transaction', params={'id': id})
    response.raise_for_status()
    if not response.json()['status']:
        raise RuntimeError(response.json()['error_msg'])
    tr_data = response.json()['data']
    return Transaction.from_api(tr_data,
                                self.get_account(account_id=tr_data['account_id']),
                                self.get_category(category_id=tr_data['category_id']),
                                self.get_transaction(tr_data['parent']) if
                                tr_data['parent'] else None)

get_transactions(self, account=None, created_at=None, from_trans=None, order=None, order_direction=None, separate_splitsid=None)

Get all transactions. This method returns an Transaction interator.

Parameters:
  • account (Account) – Account to get transactions from. Defaults to all accounts.

  • created_at (pendulum.Datetime) – Start timestamp to retrieve transactions from. Defaults to all transactions.

  • from_trans (Transaction) – Retrieve all transactions added after this transaction.

  • order (str) – Which column to sort the transactions on: date, created_at, amount, account, category, description, memo, payee, check_num.

  • order_direction – Whether to return the results in ascending or descending order. Valid parameters are DESC or ASC.

  • separate_splitsid (bool) – Whether to have splits appear in order under their parents. If you're trying to retrieve newly added transactions, set this to True or else split children will inherit the parent's created_at value

Returns:
  • Iterator

Source code in python_ccb/__init__.py
def get_transactions(self, account=None, created_at=None, from_trans=None,
                     order=None, order_direction=None, separate_splitsid=None):
    """Get all transactions. This method returns an `Transaction` interator.

    Args:
        account (Account): Account to get transactions from. Defaults to all accounts.
        created_at (pendulum.Datetime): Start timestamp to retrieve transactions from.
            Defaults to all transactions.
        from_trans (Transaction): Retrieve all transactions added after this
            transaction.
        order (str): Which column to sort the transactions on: date, created_at,
            amount, account, category, description, memo, payee, check_num.
        order_direction: Whether to return the results in ascending or descending
            order. Valid parameters are DESC or ASC.
        separate_splitsid (bool): Whether to have splits appear in order under their
            parents. If you're trying to retrieve newly added transactions, set this to
            `True` or else split children will inherit the parent's `created_at` value
    Returns:
        Iterator
    """

    limit = 250
    page = 1
    accounts = {account.id: account for account in self.get_accounts()}
    categories = {category.id: category for category in self.get_categories()}
    while True:
        params = {'account_id': account.id if account else None,
                  'created_at': created_at.to_date_string() if created_at else None,
                  'from_id': from_trans.id if from_trans else None,
                  'created_at_time': created_at.to_time_string()
                  if created_at else None,
                  'created_at_timezone':  created_at.timezone if created_at else None,
                  'order': order,
                  'order_direction': order_direction,
                  'separate_splitsid': separate_splitsid,
                  'limit': limit,
                  'page': page}
        response = self._session.get('transactions', params=params)
        response.raise_for_status()
        if not response.json()['status']:
            raise RuntimeError(response.json()['error_msg'])
        if not response.json()['data']:
            break
        for tr_data in response.json()['data']:
            yield Transaction.from_api(tr_data,
                                       accounts.get(tr_data['account_id'],
                                                    NO_ACCOUNT),
                                       categories.get(tr_data['category_id'],
                                                      NO_CATEGORY),
                                       self.get_transaction(tr_data['parent']) if
                                       tr_data['parent'] else None)
        page += 1

insert_split(self, transaction, split_list)

Insert a transaction with its splited transactions

Parameters:
  • transaction (transaction) – Transaction to insert.

  • split_list (list) – Transaction list containing the splitted transactions

Returns:
  • List of Transaction

Source code in python_ccb/__init__.py
def insert_split(self, transaction, split_list):
    """Insert a transaction with its splited transactions

    Args:
        transaction (transaction): Transaction to insert.
        split_list (list): Transaction list containing the splitted transactions

    Returns:
        List of `Transaction`
    """

    return self._manage_split('insert', transaction, split_list)

insert_transaction(self, transaction, from_account=None, to_account=None, is_split=False, split_amounts=[], split_categories=[], split_descriptions=[])

Insert a transaction

Parameters:
  • transaction (transaction) – Transaction to insert.

  • from_account (Account) – If this transaction is converted into a transfer, this is the account you're transferring from.

  • to_account (Account) – If this transaction is converted into a transfer, this is the account you're transferring to.

  • is_split (bool) – If the transaction is being split, set this to True.

  • split_amount (list) – List of float values for each split child.

  • split_categories (list) – List of categories for each split child.

  • split_descriptions (list) – List of descriptions for each split child.

Returns:
  • List of Transaction

Source code in python_ccb/__init__.py
def insert_transaction(self, transaction, from_account=None, to_account=None,
                       is_split=False, split_amounts=[], split_categories=[],
                       split_descriptions=[]):
    """Insert a transaction

    Args:
        transaction (transaction): Transaction to insert.
        from_account (Account): If this transaction is converted into a transfer,
            this is the account you're transferring from.
        to_account (Account): If this transaction is converted into a transfer,
            this is the account you're transferring to.
        is_split (bool): If the transaction is being split, set this to `True`.
        split_amount (list): List of float values for each split child.
        split_categories (list): List of categories for each split child.
        split_descriptions (list): List of descriptions for each split child.

    Returns:
        List of `Transaction`
    """

    data = {}
    return self._manage_transaction('post', transaction, data, from_account,
                                    to_account, is_split, split_amounts,
                                    split_categories, split_descriptions)

transform_transfer(self, transaction, from_account_name, to_account_name)

Transform a withdrawal or deposit transactions into a transfer

Parameters:
  • transaction (transaction) – Transaction to transform.

  • from_account_name (str) – The account you're transferring from.

  • to_account_name (str) – The account you're transferring to.

Returns:
  • List of Transaction

Warning

ClearCheckBook lets you add two accounts with the same name. In this case API behavior is unpredictable.

Source code in python_ccb/__init__.py
def transform_transfer(self, transaction, from_account_name, to_account_name):
    """Transform a withdrawal or deposit transactions into a transfer

    Args:
        transaction (transaction): Transaction to transform.
        from_account_name (str): The account you're transferring from.
        to_account_name (str): The account you're transferring to.

    Returns:
        List of `Transaction`

    Warning:
        ClearCheckBook lets you add two accounts with the same name. In this case
        API behavior is unpredictable.
    """

    accounts = self.get_accounts()
    try:
        from_account = accounts[from_account_name]
    except KeyError:
        raise ValueError(f'no account found with name {from_account_name}')
    try:
        to_account = accounts[to_account_name]
    except KeyError:
        raise ValueError(f'no account found with name {to_account_name}')
    transaction.transaction_type = TRANSFER
    return self.edit_transaction(transaction,
                                 from_account=from_account, to_account=to_account)

python_ccb.Account

Account object holds account information

Attributes:

Name Type Description
name str

Account name

type obj

One of WITHDRAW, DEPOSIT or TRANSFER.

group_id int

ID of the account group.

credit_limit float

If this is a credit card and the user has entered. a credit limit, this value will be returned.

deposit float

The float value containing the amount of deposits in this account.

jive_deposit float

The float value containing the amount of jived deposits in this account.

withdraw float

The float value containing the amount of withdrawals in this account.

jive_withdrawal float

The float value containing the amount of jived withdrawals in this account.

converted_balance float

The converted balance if this account currency differs from their global currency.

converted_jived float

the converted jived balance if this account currency differs from their global currency.

unconverted_balance float

the balance of this account in its native currency.

unconverted_jived float

the jived balance of this account in its native currency.

currency Currency

The currency for this account.

id int

The account id.

python_ccb.Category

Category object holds category information

Attributes:

Name Type Description
name str

Category name.

parent Category

If this is a child category, its category parent. None instead.

id int

The category ID.

python_ccb.Currency

Currency object holds category information

Attributes:

Name Type Description
currency_code str

The three digit currency code (eg: USD)

text str

Full name of the currency, with code. (eg: United States Dollar (USD))

code str

The HTML character code for the specified currency symbol. (eg: $ = $)

format str

How the currency should be formatted with thousands and decimal separators. (eg: #,###.## for USD)

rate float

The latest exchange rate to 1 USD

importance int

For ordering the list of currencies in a drop down list. 5 = most used and should be at the top of the list.

python_ccb.Transaction

Transaction object holds transaction information

Attributes:

Name Type Description
description str

The description for this transaction.

date pendulum.Datetime

The date for the transaction.

amount float

The amount of the transaction.

type Object

One of WITHDRAW, DEPOSIT or TRANSFER.

account Account

The account associated with this transaction.

category Category

The category associated with this transaction.

jive bool

Whether or not this transaction is jived

specialstatus str

Text that is empty or says "Transfer" or "Split".

parent Transaction

If this is a split from a split transaction, this is the parent transaction.

related_transfer str

A unique string corresponding to its related transfer.

check_num str

Text from the check number field

memo str

Text from the memo field

payee str

Text from the payee field

initial_balance bool

Boolean for whether or not this was set up as an initial balance for an account.

attachment str

If a file attachment exists, this is the URL to view it.

Account and transaction constants

The following account and transaction codes are numeric constants importable from python_ccb.

Constant Description
CASH Cash account
CHECKING Checking account
SAVINGS Savings account
CREDIT Credit Card account
INVESTMENT Investment account
WITHDRAW Withdraw transactions
DEPOSIT Deposit transactions
TRANSFER Transfer transactions
NO_ACCOUNT Special account for transactions without an assigned account
NO_CATEGORY Special category for transactions without an assigned category