Firefly III API Wrapper

The firefly_api module provides a Python wrapper for the Firefly III API, encapsulating all the interactions with the Firefly III server. This includes functionalities for managing accounts, transactions, and other related data.

FireflyIIIAPI Class

The FireflyIIIAPI class is the core of the firefly_api module. It offers various methods to interact with the Firefly III API, such as retrieving account information, listing transactions, and updating data on the server.

class firefly_api.FireflyIIIAPI(api_url: str, api_token: str)

A wrapper class for interacting with the Firefly III API. Provides methods to list, create, update, and delete accounts and transactions.

delete_transaction(transaction_id, trace_id=None)

Deletes a specific transaction by its ID from the Firefly III instance.

Parameters:

  • transaction_id (int) – The ID of the transaction to delete.

  • trace_id (str, optional) – Trace ID for the request.

Returns:

A confirmation message if the transaction is successfully deleted, else raises an exception.

Return type:

str

get_about_info()

Retrieves information about the Firefly III instance.

Returns:

A dictionary containing about information if successful, else raises an exception.

Return type:

dict

get_transaction(transaction_id, trace_id=None)

Retrieves a specific transaction by its ID from the Firefly III instance.

Parameters:

  • transaction_id (int) – The ID of the transaction to retrieve.

  • trace_id (str, optional) – Trace ID for the request.

Returns:

The requested Transaction object if found, else raises an exception.

Return type:

Transaction

list_accounts(date=None, account_type=None) → List[Account]

Lists accounts from the Firefly III instance with optional filtering.

Parameters:

  • date (str, optional) – Date filter for accounts.

  • account_type (str, optional) – Type of accounts to filter.

Returns:

A list of Account objects.

Return type:

List[Account]

list_transactions(start=None, end=None, transaction_type=None) → List[Transaction]

Lists transactions from the Firefly III instance with optional filtering.

Parameters:

  • start (str, optional) – Start date for filtering transactions.

  • end (str, optional) – End date for filtering transactions.

  • transaction_type (str, optional) – Type of transactions to filter.

Returns:

A list of Transaction objects.

Return type:

List[Transaction]

put_transaction(transaction: Transaction)

Adds transactions to Firefly III.

Parameters:

transaction (List[Transaction]) – A transactions to be added.

store_account(account_data, trace_id=None)

Stores a new account in the Firefly III instance.

Parameters:

  • account_data (dict) – Data of the account to be stored.

  • trace_id (str, optional) – Trace ID for the request.

Returns:

The stored Account object if successful, else raises an exception.

Return type:

Account

store_transaction(transaction_data, trace_id=None)

Stores a new transaction in the Firefly III instance.

Parameters:

  • transaction_data (dict) – Data of the transaction to be stored.

  • trace_id (str, optional) – Trace ID for the request.

Returns:

The stored Transaction object if successful, else raises an exception.

Return type:

Transaction

update_transaction(transaction_id, updated_transaction_data)

Updates a specific transaction by its ID in the Firefly III instance.

Parameters:

  • transaction_id (int) – The ID of the transaction to update.

  • updated_transaction_data (dict) – The new data for updating the transaction.

Returns:

The updated Transaction object if successful, else raises an exception.

Return type:

Transaction

Usage

To use the FireflyIIIAPI class, initialize it with the base URL of your Firefly III instance and the API token. Once initialized, you can call its methods to perform various operations with the Firefly III server.

Example:

from firefly_api import FireflyIIIAPI

# Initialize the API wrapper
api = FireflyIIIAPI(base_url="https://your-firefly-instance.com/api/v1", api_token="your_api_token")

# Fetching account data
accounts = api.list_accounts()

# Listing transactions for a specific period
transactions = api.list_transactions(start="2024-01-01", end="2024-01-31")

This setup allows for seamless integration with Firefly III, enabling the application to manage financial data effectively.