Reference

Adjuster(credentials)

Abstract class which modifies transactions according to concrete implementation. You need to create your own child class and implement the filter()and adjust() method in it according to your needs. It has attributes which allow you to lookup categories and payees from your budget.

Attributes:
  • categories (CategoryRepo) –

    Collection of current categories in YNAB budget

  • payees (PayeeRepo) –

    Collection of current payees in YNAB budget

  • accounts (AccountRepo) –

    Collection of current accounts in YNAB budget

  • transactions (List[Transaction]) –

    All current non deleted transactions from YNAB Account

  • credentials –

    Credentials for YNAB API

adjust(transaction, modifier) abstractmethod

Function which implements the actual modification of a transaction. It receives the original transaction from YNAB and a prefilled modifier. The modifier can be altered and must be returned.

Parameters:
  • transaction (Transaction) –

    Original transaction

  • modifier (Modifier) –

    Transaction modifier prefilled with values from original transaction. All attributes can be changed and will modify the transaction
Returns:
  • Modifier –

    Method needs to return the transaction modifier after modification

apply()

Function which applies filter & adjust function on transactions as per implementation of the two methods.

Returns:
  • List[ModifiedTransaction] –

    Filtered list of modified transactions (only transactions with actual changes are returned)
Raises:
  • SignatureError –

    if signature of implemented adjuster functions is not compatible

  • AdjustError –

    if there is any error during the adjust process

fetch_transaction(transaction_id)

Fetches an individual transaction from the YNAB account

Parameters:
  • transaction_id (str) –

    Transaction ID of the transaction to be fetched

filter(transactions) abstractmethod

Function which implements filtering for the list of transactions from YNAB account. It receives a list of the original transactions which can be filtered. Must return the filtered list or just the list if no filtering is intended.

Parameters:
  • transactions (List[Transaction]) –

    List of original transactions from YNAB
Returns:
  • List[Transaction] –

    Method needs to return a list of filtered transactions

update(modified_transactions)

Updates the modified transactions in YNAB

Parameters:
  • modified_transactions (List[ModifiedTransaction]) –

    List of modified transactions to be updated in YNAB
Returns:
  • List[Transaction] –

    list of modified transactions
Raises:
  • HTTPError –

    if there is any error with the YNAB API (e.g. wrong credentials)

Repos

repos.CategoryRepo

Repository which holds all categories from your YNAB budget

Attributes:
  • _categories –

    List of Category Groups in YNAB budget

fetch_all()

Fetches all Categories from YNAB budget

Returns:
  • Dict[str, List[Category]] –

    Dictionary with group names as keys and list of categories as values

fetch_by_id(category_id)

Fetches a YNAB category by its ID

Parameters:
  • category_id (str) –

    ID of the category
Returns:
  • Category –

    Returns the matched category
Raises:
  • NoMatchingCategoryError –

    if no matching category is found

fetch_by_name(category_name, group_name=None)

Fetches a YNAB category by its name

Parameters:
  • category_name (str) –

    Name of the category to fetch

  • group_name (str, default: None ) –

    Optional name of the group the category belongs to
Returns:
  • Category –

    Matched category by name
Raises:
  • NoMatchingCategoryError –

    if no matching category is found

  • MultipleMatchingCategoriesError –

    if multiple matching categories are found

repos.PayeeRepo

Repository which holds all payees from your YNAB budget

Attributes:
  • _payees –

    List of payees in YNAB budget

fetch_all()

Fetches all payees from YNAB budget

Returns:
  • List[Payee] –

    List of all payees in budget

fetch_by_id(payee_id)

Fetches a payee by its ID

Parameters:
  • payee_id (str) –

    ID of the payee to fetch
Returns:
  • Payee –

    matched payee
Raises:
  • NoMatchingPayeeError –

    if no matching payee is found

fetch_by_name(payee_name)

Fetches a payee by its name

Parameters:
  • payee_name (str) –

    Name of the payee to fetch
Returns:
  • Payee –

    Matched Payee
Raises:
  • NoMatchingPayeeError –

    if no matching payee is found

fetch_by_transfer_account_id(transfer_account_id)

Fetches a transfer payee by the target account id

Parameters:
  • transfer_account_id (str) –

    The id of the target account for the transfer
Returns:
  • Payee –

    matched transfer payee
Raises:
  • NoMatchingPayeeError –

    if no matching payee is found

repos.AccountRepo

Repository which holds all accounts from your YNAB budget

fetch_all()

Fetches all accounts from YNAB budget

Returns:
  • List[Account] –

    list with accounts

fetch_by_id(account_id)

Fetches a YNAB account by its ID

Parameters:
  • account_id (str) –

    ID of the account
Returns:
  • Account –

    Matched account
Raises:
  • NoMatchingAccountError –

    if no matching account is found

fetch_by_name(account_name)

Fetches a YNAB account by its name

Parameters:
  • account_name (str) –

    Name of the account to fetch
Returns:
  • Account –

    Matched account
Raises:
  • NoMatchingAccountError –

    if no matching account is found

Models

models.Credentials dataclass

Credentials to use for YNAB

Attributes:
  • token (str) –

    The YNAB token to use

  • budget (str) –

    The YNAB budget id to use

  • account (Optional[str]) –

    Optionally the YNAB account id to use

models.Transaction dataclass

Represents original transaction from YNAB

Attributes:
  • id (str) –

    The transaction id

  • account (Account) –

    The account of the transaction

  • amount (int) –

    The transaction amount in milliunits format

  • category (Optional[Category]) –

    The category of the original transaction

  • transaction_date (date) –

    The date of the original transaction

  • memo (Optional[str]) –

    The memo of the original transaction

  • payee (Payee) –

    The payee of the original transaction

  • flag_color (Optional[Literal['red', 'green', 'blue', 'orange', 'purple', 'yellow']]) –

    The flag color of the original transaction

  • import_payee_name (Optional[str]) –

    The payee as recorded by YNAB on import

  • import_payee_name_original (Optional[str]) –

    The original payee or memo as recorded by the bank

  • approved (bool) –

    approval status of the original transaction

  • cleared (Literal['uncleared', 'cleared', 'reconciled']) –

    clearance state of the original transaction

  • transfer_transaction_id (Optional[str]) –

    id of the originating transaction if transaction is transfer

models.SubTransaction dataclass

Represents an YNAB Subtransaction as part of an existing split transaction

Attributes:
  • payee (Payee) –

    The payee of the subtransaction

  • category (Optional[Category]) –

    The category of the subtransaction

  • amount (int) –

    The amount of the subtransaction in milliunits

  • memo (Optional[str]) –

    The memo of the subtransaction

  • transfer_transaction_id (Optional[str]) –

    The transaction id of the correlated transaction in the transfer account

models.Modifier

Bases: BaseModel

Transaction object prefilled with values from original transaction which can take modified values

Attributes:
  • category (Optional[Category]) –

    The category of the transaction

  • transaction_date (date) –

    The date of the transaction

  • memo (Optional[str]) –

    The memo of the transaction

  • payee (Payee) –

    The payee of the transaction

  • flag_color (Optional[Literal['red', 'green', 'blue', 'orange', 'purple', 'yellow']]) –

    The flag color of the transaction

  • subtransactions (List[ModifierSubTransaction]) –

    The subtransactions of the transaction

  • cleared (Literal['uncleared', 'cleared', 'reconciled']) –

    Clearance status

  • approved (bool) –

    Approval status of the transaction

  • account (Account) –

    The account of the transaction

models.ModifierSubTransaction

Bases: BaseModel

YNAB Subtransaction object for creating split transactions. To be used as element in subtransaction attribute of Transaction class

Attributes:
  • amount (int) –

    The amount of the subtransaction in milliunits

  • category (Optional[Category]) –

    The category of the subtransaction

  • payee (Optional[Payee]) –

    The payee of the subtransaction

  • memo (Optional[str]) –

    The memo of the subtransaction

models.ModifiedTransaction

Bases: BaseModel

changed_attributes: dict property

Returns a dictionary representation of the modified values and the original transaction

as_dict()

Returns a dictionary representation of the transaction which is used for the update call to YNAB

is_changed()

Helper function to determine if transaction has been altered as compared to original one

Returns:
  • bool –

    True if values from original transaction have been altered, False otherwise

models.Category

Bases: BaseModel

Category object of YNAB budget

Attributes:
  • id (str) –

    The ID of the category

  • name (str) –

    The name of the category

models.Payee

Bases: BaseModel

Represents a YNAB Payee

Attributes:
  • name (Optional[str]) –

    The name of the payee

  • id (Optional[str]) –

    The ID of the payee

  • transfer_account_id (Optional[str]) –

    The ID of the transfer account in case payee is of type "Transfer:[account]"

models.Account dataclass

Account object from YNAB

Attributes:
  • id (str) –

    the id of the account

  • name (str) –

    the name of the account

Exceptions

exceptions.AdjustError

Bases: Exception

Raised when an error occurs while running the factory on a transaction or during validation of the returned results of the run

exceptions.NoMatchingCategoryError

Bases: Exception

Raised when no matching category is found in the specified budget

exceptions.MultipleMatchingCategoriesError

Bases: Exception

Raised when multiple matching categories are found in the specified budget. This can be the case when categories have the same name under different category groups

exceptions.NoMatchingPayeeError

Bases: Exception

Raised when no matching payee is found in the specified budget

exceptions.NoMatchingAccountError

Bases: Exception

Raised when no matching account is found in the specified budget

exceptions.ExistingSubTransactionError

Bases: Exception

Raised when subtransactions are specified in the modifier for a transaction which already has subtransactions. YNAB currently doesn't allow updating splits of existing split transactions via the API