Reference
python_ccb.ClearCheckBook
This class connects to ClearCheckBook
Parameters: |
|
---|
delete_transaction(self, transaction)
Delete a transaction
Parameters: |
|
---|
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: |
|
---|
Returns: |
|
---|
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: |
|
---|
Returns: |
|
---|
Exceptions: |
|
---|
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: |
|
---|
Returns: |
|
---|
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: |
|
---|
Returns: |
|
---|
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: |
|
---|
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: |
|
---|
Returns: |
|
---|
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: |
|
---|
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: |
|
---|
Returns: |
|
---|
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: |
|
---|
Returns: |
|
---|
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: |
|
---|
Returns: |
|
---|
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: |
|
---|
Returns: |
|
---|
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: |
|
---|
Returns: |
|
---|
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: |
|
---|
Returns: |
|
---|
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 |