aioynab¶

YNAB API client implemented using python 3 asyncio.

Install¶

aioynab can easily be installed using pip and python >=3.5.3:

$ pip install aioynab

Quick Start¶

First create a personal access token in your YNAB account. Create a client with that value like the example below.

import asyncio

from aioynab.client import Client


loop = asyncio.get_event_loop()
client = Client('ynab-personal-access-token')
budgets = loop.run_until_complete(client.budgets()))
budget_id = budgets['budgets'][0]['budget_id']
accounts = loop.run_until_complete(client.accounts(budget_id))
account_id = accounts['accounts'][0]['account_id']
transactions = loop.run_until_complete(client.account_transactions(budget_id, account_id))

Return Values¶

The return values from all client functions return the value of the data key of the YNAB response. For example, the following YNAB response from the /user endpoint:

{
  "data": {
    "user": {
      "id": "1a2f3f4e-5c01-4678-8134-c11e278fa111"
      }
    }
}

Would result in the following return value when calling the user method:

>>> client = Client('access-token')
>>> client.user()
{'user': {'id': '1a2f3f4e-5c01-4678-8134-c11e278fa111'}}

Consult the YNAB API endpoint documentation for the schema of the response for each endpoint that the client interacts with.

Module Documentation¶

aioynab.client.BASE_URL = 'https://api.youneedabudget.com/v1'¶: The base API URL for YNAB.

class aioynab.client.Client(personal_access_token, loop=None, session=None)[source]¶

Bases: object

A client for the YNAB API.

Parameters:	personal_access_token (`str`) – The YNAB personal access token. Create one at https://app.youneedabudget.com/settings/developer. loop (`Optional`[`AbstractEventLoop`]) – Optional event loop, one will be created if not passed. session (`Optional`[`ClientSession`]) – Optional aiohttp client session, one will be created if not passed.

_request(endpoint, method='GET', params=None, body=None)[source]¶

Performs a http request and returns the json response.

Parameters:	endpoint (`str`) – The API endpoint. method (`str`) – The HTTP method to use (GET, POST, PUT). params (`Optional`[`dict`]) – Any parameters to send with the request. body (`Optional`[`dict`]) – A json body to send with the request.
Return type:	`dict`
Returns:	The json data as a dict.
Raises:	YNABAPIError – If there is an api error.

account(budget_id, account_id)[source]¶

Returns a single account associated with a budget.

Corresponds to the /budget/{budget_id}/accounts/{account_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget to look up. account_id (`str`) – The ID of the account.
Return type:	`dict`
Returns:	A dict of the account.

account_transactions(budget_id, account_id, since_date=None, type=None, last_knowledge_of_server=None)[source]¶

Returns all transactions for a specified account.

Corresponds to the /budgets/{budget_id}/accounts/{account_id}/transactions endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. account_id (`str`) – The ID of the account. since_date (`Optional`[`str`]) – If specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g. 2016-12-30). type (`Optional`[`str`]) – If specified, only transactions of the specified type will be included. ‘uncategorized’and ‘unapproved’ are currently supported. last_knowledge_of_server (`Optional`[`int`]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type:	`dict`
Returns:	A dict of all transactions for the requested account.

accounts(budget_id, last_knowledge_of_server=None)[source]¶

Returns all accounts associated with the budget.

Corresponds to the /budget/{budget_id}/accounts endpoint.

Parameters:	budget_id (`str`) – The ID of the budget to look up. last_knowledge_of_server (`Optional`[`int`]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type:	`dict`
Returns:	A dict containing all accounts.

budget(budget_id, last_knowledge_of_server=None)[source]¶

Returns a single budget with all related entities.

This resource is effectively a full budget export. Corresponds to the /budget/{budget_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget to look up. last_knowledge_of_server (`Optional`[`int`]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type:	`dict`
Returns:	A dict containing the requested budget.

budget_month(budget_id, month)[source]¶

Returns a single budget month.

Corresponds to the /budgets/{budget_id}/months/{month} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. month (`str`) – The budget month in ISO format (e.g. 2016-12-01) (‘current’ can also be used to specify the current calendar month (UTC)).
Return type:	`dict`
Returns:	A dict for the requested budget month.

budget_months(budget_id, last_knowledge_of_server=None)[source]¶

Returns all budget months.

Corresponds to the /budgets/{budget_id}/months endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. last_knowledge_of_server (`Optional`[`int`]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type:	`dict`
Returns:	A dict of all budget months.

budget_settings(budget_id)[source]¶

Returns settings for a budget.

Corresponds to the /budget/{budget_id/settings endpont.

Parameters:	budget_id (`str`) – The ID of the budget.
Return type:	`dict`
Returns:	The budget settings data as a dict.

budgets()[source]¶

Returns budgets list with summary information.

Corresponds to the /budgets endpoint.

Reutrns:	A dict containing all budgets.
Return type:	`dict`

categories(budget_id, last_knowledge_of_server=None)[source]¶

Returns all categories grouped by category group.

Corresponds to the /budgets/{budget_id}/categories endpoint.

Parameters:	budget_id (`str`) – The ID of the budget to look up. last_knowledge_of_server (`Optional`[`int`]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type:	`dict`
Returns:	A dict of all categories.

category(budget_id, category_id)[source]¶

Returns a single category.

Amounts (budgeted, activity, balance, etc.) are specific to the current budget month (UTC). Corresponds to the /budgets/{budget_id}/categories/{category_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. category_id (`str`) – The ID of the category.
Return type:	`dict`
Returns:	A dict of the requested category.

category_month(budget_id, category_id, month)[source]¶

Returns a single category for a specific budget month.

Amounts (budgeted, activity, balance, etc.) are specific to the current budget month (UTC). Corresponds to the /budgets/{budget_id}/months/{month}/categories/{category_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. category_id (`str`) – The ID of the category. month (`str`) – The budget month in ISO format (e.g. 2016-12-01) (‘current’ can also be used to specify the current calendar month (UTC)).
Return type:	`dict`
Returns:	A dict for the specified category and month.

category_transactions(budget_id, category_id, since_date=None, type=None, last_knowledge_of_server=None)[source]¶

Returns all transactions for a specified category.

Corresponds to the /budgets/{budget_id}/categories/{category_id}/transactions endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. category_id (`str`) – The ID of the category. since_date (`Optional`[`str`]) – If specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g. 2016-12-30). type (`Optional`[`str`]) – If specified, only transactions of the specified type will be included. ‘uncategorized’and ‘unapproved’ are currently supported. last_knowledge_of_server (`Optional`[`int`]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type:	`dict`
Returns:	A dict of all transactions for the requested category.

close()[source]¶: Closes the session.

create_transactions(budget_id, transaction=None, transactions=None)[source]¶

Creates a single transaction or multiple transactions.

One of transaction or transactions must be specified, but not both. Corresponds to the /budgets/{budget_id}/transactions endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. transaction (`Optional`[`dict`]) – The transaction to create. transactions (`Optional`[`List`[`dict`]]) – The list of transactions to create.
Return type:	`dict`
Returns:	A dict of the created transaction(s).
Raises:	ValueError – If both transaction and transactions are provided or neither are provided.

locations_payee(budget_id, payee_id)[source]¶

Returns all payee locations for the specified payee.

Corresponds to the /budgets/{budget_id}/payees/{payee_id}/payee_locations endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. payee_id (`str`) – The ID of the payee.
Return type:	`dict`
Returns:	A dict of locations for the requested payee.

payee(budget_id, payee_id)[source]¶

Returns single payee.

Corresponds to the /budgets/{budget_id}/payees/{payee_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. payee_id (`str`) – The ID of the payee.
Return type:	`dict`
Returns:	A dict of the requested payee.

payee_location(budget_id, payee_location_id)[source]¶

Returns all payee locations.

Corresponds to the /budgets/{budget_id}/payee_locations/{payee_location_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. payee_location_id (`str`) – The ID of the payee location.
Return type:	`dict`
Returns:	A dict of the requested payee location.

payee_locations(budget_id)[source]¶

Returns all payee locations.

Corresponds to the /budgets/{budget_id}/payee_locations endpoint.

Parameters:	budget_id (`str`) – The ID of the budget.
Return type:	`dict`
Returns:	A dict of all payee locations.

payee_transactions(budget_id, payee_id, since_date=None, type=None, last_knowledge_of_server=None)[source]¶

Returns all transactions for a specified payee.

Corresponds to the /budgets/{budget_id}/payees/{payee_id}/transactions endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. payee_id (`str`) – The ID of the payee. since_date (`Optional`[`str`]) – If specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g. 2016-12-30). type (`Optional`[`str`]) – If specified, only transactions of the specified type will be included. ‘uncategorized’and ‘unapproved’ are currently supported. last_knowledge_of_server (`Optional`[`int`]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type:	`dict`
Returns:	A dict of all transactions for the requested payee.

payees(budget_id, last_knowledge_of_server=None)[source]¶

Returns all payees.

Corresponds to the /budgets/{budget_id}/payees endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. last_knowledge_of_server (`Optional`[`int`]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type:	`dict`
Returns:	A dict of all payees.

scheduled_transaction(budget_id, scheduled_transaction_id)[source]¶

Returns all scheduled transactions.

Corresponds to the /budgets/{budget_id}/scheduled_transactions/{scheduled_transaction_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. scheduled_transaction_id (`str`) – The ID of the scheduled transaction.
Return type:	`dict`
Returns:	A dict of all scheduled transactions.

scheduled_transactions(budget_id)[source]¶

Returns all scheduled transactions.

Corresponds to the /budgets/{budget_id}/scheduled_transactions endpoint.

Parameters:	budget_id (`str`) – The ID of the budget.
Return type:	`dict`
Returns:	A dict of all scheduled transactions.

transaction(budget_id, transaction_id)[source]¶

Returns a single transaction.

Corresponds to the /budgets/{budget_id}/transactions/{transaction_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. transaction_id (`str`) – The ID of the transaction.
Return type:	`dict`
Returns:	A dict of the requested transaction.

transactions(budget_id, since_date=None, type=None, last_knowledge_of_server=None)[source]¶

Returns budget transactions.

Corresponds to the /budgets/{budget_id}/transactions endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. since_date (`Optional`[`str`]) – If specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g. 2016-12-30). type (`Optional`[`str`]) – If specified, only transactions of the specified type will be included. ‘uncategorized’and ‘unapproved’ are currently supported. last_knowledge_of_server (`Optional`[`int`]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type:	`dict`
Returns:	A dict of all transactions for the budget.

update_category_month(budget_id, category_id, month, data)[source]¶

Updates a category for a specific month.

Corresponds to the /budgets/{budget_id}/months/{month}/categories/{category_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. category_id (`str`) – The ID of the category. month (`str`) – The budget month in ISO format (e.g. 2016-12-01) (‘current’ can also be used to specify the current calendar month (UTC)). data (`dict`) – A dict containing the fields/values to update.
Return type:	`dict`
Returns:	A dict of the category for the month.

update_transaction(budget_id, transaction_id, data)[source]¶

Updates a single transaction.

Corresponds to the /budgets/{budget_id}/transactions/{transaction_id} endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. transaction_id (`str`) – The ID of the transaction. data (`dict`) – A dict containing the fields/values to update.
Return type:	`dict`
Returns:	A dict of the updated transaction.

update_transactions(budget_id, transaction=None, transactions=None)[source]¶

Updates multiple transactions, by ‘id’ or ‘import_id’.

One of transaction or transactions must be specified, but not both. Corresponds to the /budgets/{budget_id}/transactions endpoint.

Parameters:	budget_id (`str`) – The ID of the budget. transaction (`Optional`[`dict`]) – The transaction to update. transactions (`Optional`[`List`[`dict`]]) – The list of transactions to updates.
Return type:	`dict`
Returns:	A dict of the updated transaction(s).
Raises:	ValueError – If both transaction and transactions are provided or neither are provided.

user()[source]¶

Returns authenticated user information.

Corresponds to the /user endpoint.

Return type:	`dict`
Returns:	A dict with user data.

exception aioynab.client.YNABAPIError(status, error_data)[source]¶

Bases: Exception

An error class for YNAB API errors.

Parameters:	status (`int`) – The http status code. error_data (`dict`) – The error data returned in the response.

CHANGELOG¶

v0.1.1 (2019-03-29)¶

Made uvloop optional. Install with pip by specifying uvloop in extras.

v0.1.0 (2019-03-27)¶

Initial release.