Skip to content

Budgets

budgets

Classes:

  • BudgetCategory –

    Represents budget information for a single category in a specific month.

  • BudgetCategoryGroup –

    Represents budget information for a category group and all its categories in a specific month.

  • IncomeCategory –

    Represents budget information for a single income category in a specific month.

  • IncomeCategoryGroup –

    Represents income information for a category group and all its categories in a specific month.

  • BaseBudget –

    Base class for budget information for a single month.

  • EnvelopeBudget –

    Budget information for envelope budgeting mode for a single month.

  • TrackingBudget –

    Budget information for tracking budgeting mode for a single month.

  • BudgetList –

    A list of budget objects with helper methods for accessing budget information.

Functions:

  • get_budget_history –

    Returns the budget history from the first available month to the given month, as iterable.

BudgetCategory dataclass 

BudgetCategory(
    database_object: Categories,
    spent: Decimal,
    accumulated_balance: Decimal,
    budget: BaseBudgets | None = None,
)

Bases: _HasDatabaseObject

Represents budget information for a single category in a specific month.

This dataclass contains both the budgeted amount and actual spending information for a category, along with balance calculations.

Parameters:

  • database_object

    (Categories) –

    The category database object this budget information applies to.

  • spent

    (Decimal) –

    The actual amount spent in this category this month (typically negative).

  • accumulated_balance

    (Decimal) –

    The balance including carryover from previous months.

    This reflects the values displayed on the Actual frontend.

  • budget

    (BaseBudgets | None, default: None ) –

    The underlying budget database record, if it exists.

    If a budget was not set for the month, it will be set to None, and budgeted amount assumed to be zero.

Methods:

  • as_dict –

    Converts the budget category to a dictionary representation.

Attributes:

  • database_object (Categories) –

    The category database object this budget information applies to.

  • spent (Decimal) –

    The actual amount spent in this category this month (typically negative).

  • accumulated_balance (Decimal) –

    The balance including carryover from previous months.

  • budget (BaseBudgets | None) –

    The underlying budget database record, if it exists.

  • budgeted (Decimal) –

    The amount budgeted for this category in this month.

  • balance (Decimal) –

    The simple balance (budgeted plus spent) for this month only.

  • carryover (bool) –

    Whether this category has carryover enabled (rolls over balance to next month).

  • hidden (bool) –

    Whether this category is hidden.

  • is_income (bool) –

    Whether this category is an income category.

database_object instance-attribute 

database_object: Categories

The category database object this budget information applies to.

spent instance-attribute 

spent: Decimal

The actual amount spent in this category this month (typically negative).

accumulated_balance instance-attribute 

accumulated_balance: Decimal

The balance including carryover from previous months.

This reflects the values displayed on the Actual frontend.

budget class-attribute instance-attribute 

budget: BaseBudgets | None = None

The underlying budget database record, if it exists.

If a budget was not set for the month, it will be set to None, and budgeted amount assumed to be zero.

budgeted property 

budgeted: Decimal

The amount budgeted for this category in this month.

balance property 

balance: Decimal

The simple balance (budgeted plus spent) for this month only.

If you are looking for the accumulated balance (taking into account previous months and carryover flags, use accumulated_balance instead.

carryover property 

carryover: bool

Whether this category has carryover enabled (rolls over balance to next month).

hidden property 

hidden: bool

Whether this category is hidden.

is_income property 

is_income: bool

Whether this category is an income category.

as_dict 

as_dict() -> dict

Converts the budget category to a dictionary representation.

It's important to note that the property balance represents the accumulated_balance.

Source code in actual/budgets.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def as_dict(self) -> dict:
    """
    Converts the budget category to a dictionary representation.

    It's important to note that the property `balance` represents the `accumulated_balance`.
    """
    return {
        "id": self.id,
        "name": self.name,
        "is_income": self.is_income,
        "hidden": self.hidden,
        "budgeted": self.budgeted,
        "spent": self.spent,
        "balance": self.accumulated_balance,
        "carryover": self.carryover,
    }

BudgetCategoryGroup dataclass 

BudgetCategoryGroup(
    database_object: CategoryGroups,
    categories: list[BudgetCategory],
)

Bases: _HasDatabaseObject

Represents budget information for a category group and all its categories in a specific month.

A category group contains multiple categories and aggregates their budget information.

Parameters:

  • database_object

    (CategoryGroups) –

    The category group database object this budget information applies to.

  • categories

    (list[BudgetCategory]) –

    List of BudgetCategory objects for all categories in this group.

Methods:

  • as_dict –

    Converts the budget category group to a dictionary representation, including nested categories.

Attributes:

database_object instance-attribute 

database_object: CategoryGroups

The category group database object this budget information applies to.

categories instance-attribute 

categories: list[BudgetCategory]

List of BudgetCategory objects for all categories in this group.

budgeted property 

budgeted: Decimal

Sum of all budgeted amounts from the categories under this category group.

spent property 

spent: Decimal

Sum of all spent amounts from the categories under this category group.

accumulated_balance property 

accumulated_balance: Decimal

Sum of all accumulated balances from the categories under this category group.

hidden property 

hidden: bool

Whether this category is hidden.

is_income property 

is_income: bool

Whether this category is an income category.

as_dict 

as_dict() -> dict

Converts the budget category group to a dictionary representation, including nested categories.

It's important to note that the property balance represents the accumulated_balance.

Source code in actual/budgets.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def as_dict(self) -> dict:
    """
    Converts the budget category group to a dictionary representation, including nested categories.

    It's important to note that the property `balance` represents the `accumulated_balance`.
    """
    return {
        "id": self.id,
        "name": self.name,
        "is_income": self.is_income,
        "hidden": self.hidden,
        "budgeted": self.budgeted,
        "spent": self.spent,
        "balance": self.accumulated_balance,
        "categories": [c.as_dict() for c in self.categories],
    }

IncomeCategory dataclass 

IncomeCategory(
    database_object: Categories,
    received: Decimal,
    budgeted: Decimal = Decimal(0),
    budget: ReflectBudgets | None = None,
)

Bases: _HasDatabaseObject

Represents budget information for a single income category in a specific month.

This dataclass contains both the budgeted amount and actual spending information for a category, along with balance calculations.

Parameters:

  • database_object

    (Categories) –

    The category database object this budget information applies to.

  • received

    (Decimal) –

    The amount of money received in this month.

  • budgeted

    (Decimal, default: Decimal('0') ) –

    The amount budgeted for this category in this month. Only exists for TrackingBudget.

  • budget

    (ReflectBudgets | None, default: None ) –

    The underlying budget database record, if it exists. Only exists for TrackingBudget

    If a budget was not set for the month, it will be set to None, and budgeted amount assumed to be zero.

Methods:

  • as_dict –

    Converts the income category to a dictionary representation.

Attributes:

  • database_object (Categories) –

    The category database object this budget information applies to.

  • received (Decimal) –

    The amount of money received in this month.

  • budgeted (Decimal) –

    The amount budgeted for this category in this month. Only exists for TrackingBudget.

  • budget (ReflectBudgets | None) –

    The underlying budget database record, if it exists. Only exists for TrackingBudget

  • hidden (bool) –

    Whether this category is hidden.

  • is_income (bool) –

    Whether this category is an income category.

database_object instance-attribute 

database_object: Categories

The category database object this budget information applies to.

received instance-attribute 

received: Decimal

The amount of money received in this month.

budgeted class-attribute instance-attribute 

budgeted: Decimal = Decimal(0)

The amount budgeted for this category in this month. Only exists for TrackingBudget.

budget class-attribute instance-attribute 

budget: ReflectBudgets | None = None

The underlying budget database record, if it exists. Only exists for TrackingBudget

If a budget was not set for the month, it will be set to None, and budgeted amount assumed to be zero.

hidden property 

hidden: bool

Whether this category is hidden.

is_income property 

is_income: bool

Whether this category is an income category.

as_dict 

as_dict() -> dict

Converts the income category to a dictionary representation.

Source code in actual/budgets.py 
186
187
188
189
190
191
192
193
194
195
196
197
def as_dict(self) -> dict:
    """
    Converts the income category to a dictionary representation.
    """
    return {
        "id": self.id,
        "name": self.name,
        "is_income": self.is_income,
        "hidden": self.hidden,
        "received": self.received,
        "budgeted": self.budgeted,
    }

IncomeCategoryGroup dataclass 

IncomeCategoryGroup(
    database_object: CategoryGroups,
    categories: list[IncomeCategory],
)

Bases: _HasDatabaseObject

Represents income information for a category group and all its categories in a specific month.

An income category group contains multiple income categories and aggregates their budget information.

Parameters:

  • database_object

    (CategoryGroups) –

    The category group database object this budget information applies to.

  • categories

    (list[IncomeCategory]) –

    List of IncomeCategory objects for all income categories in this group.

Methods:

  • as_dict –

    Converts the income category group to a dictionary representation, including nested categories.

Attributes:

  • database_object (CategoryGroups) –

    The category group database object this budget information applies to.

  • categories (list[IncomeCategory]) –

    List of IncomeCategory objects for all income categories in this group.

  • received (Decimal) –

    Sum of all received amounts from the income categories under this income category group.

  • budgeted (Decimal) –

    Sum of all budgeted amounts from the income categories under this income category group.

  • hidden (bool) –

    Whether this category is hidden.

  • is_income (bool) –

    Whether this category is an income category.

database_object instance-attribute 

database_object: CategoryGroups

The category group database object this budget information applies to.

categories instance-attribute 

categories: list[IncomeCategory]

List of IncomeCategory objects for all income categories in this group.

received property 

received: Decimal

Sum of all received amounts from the income categories under this income category group.

budgeted property 

budgeted: Decimal

Sum of all budgeted amounts from the income categories under this income category group.

Only exists for TrackingBudget.

hidden property 

hidden: bool

Whether this category is hidden.

is_income property 

is_income: bool

Whether this category is an income category.

as_dict 

as_dict() -> dict

Converts the income category group to a dictionary representation, including nested categories.

Source code in actual/budgets.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
def as_dict(self) -> dict:
    """
    Converts the income category group to a dictionary representation, including nested categories.
    """
    return {
        "id": self.id,
        "name": self.name,
        "is_income": self.is_income,
        "hidden": self.hidden,
        "received": self.received,
        "budgeted": self.budgeted,
        "categories": [c.as_dict() for c in self.categories],
    }

BaseBudget dataclass 

BaseBudget(
    month: date,
    category_groups: list[BudgetCategoryGroup],
    income_category_groups: list[IncomeCategoryGroup],
)

Base class for budget information for a single month.

This is the parent class for both EnvelopeBudget and TrackingBudget, containing common properties and methods for budget calculations.

Parameters:

  • month

    (date) –

    The month this budget applies to (always the first day of the month).

  • category_groups

    (list[BudgetCategoryGroup]) –

    List of BudgetCategoryGroup objects containing all budget categories.

  • income_category_groups

    (list[IncomeCategoryGroup]) –

    List of IncomeCategoryGroup objects containing all income categories.

Methods:

  • from_category –

    Returns the budget category for the given category if it exists.

Attributes:

month instance-attribute 

month: date

The month this budget applies to (always the first day of the month).

category_groups instance-attribute 

category_groups: list[BudgetCategoryGroup]

List of BudgetCategoryGroup objects containing all budget categories.

income_category_groups instance-attribute 

income_category_groups: list[IncomeCategoryGroup]

List of IncomeCategoryGroup objects containing all income categories.

received property 

received: Decimal

Total income for this month.

budgeted property 

budgeted: Decimal

The amount of money distributed on all budgets for this month.

Keep in mind that, while frontend shows this as a negative number, the budgeted amount is always positive.

accumulated_balance property 

accumulated_balance: Decimal

Sum of all balances from all categories.

spent property 

spent

Expenses for the current month.

It is the sum of all money spent on the month.

categories property 

categories: Iterator[BudgetCategory]

List all categories in this budget.

from_category 

from_category(
    category: Categories,
) -> BudgetCategory | None

Returns the budget category for the given category if it exists.

Source code in actual/budgets.py 
297
298
299
300
301
302
303
def from_category(self, category: Categories) -> BudgetCategory | None:
    """Returns the budget category for the given category if it exists."""
    for group in self.category_groups:
        for cat in group.categories:
            if cat.database_object.id == category.id:
                return cat
    return None

EnvelopeBudget dataclass 

EnvelopeBudget(
    month: date,
    category_groups: list[BudgetCategoryGroup],
    income_category_groups: list[IncomeCategoryGroup],
    for_next_month: Decimal,
    last_month_overspent: Decimal,
    from_last_month: Decimal,
)

Bases: BaseBudget

Budget information for envelope budgeting mode for a single month.

Envelope budgeting is the default budgeting mode in Actual Budget, where money is allocated to specific categories and can be carried over between months.

Parameters:

  • month

    (date) –

  • category_groups

    (list[BudgetCategoryGroup]) –

  • income_category_groups

    (list[IncomeCategoryGroup]) –

  • for_next_month

    (Decimal) –

    The amount of money held for the next month.

  • last_month_overspent

    (Decimal) –

    The overspent amount from the previous month.

  • from_last_month

    (Decimal) –

    The amount of money inherited from the previous month.

Methods:

  • as_dict –

    Converts the envelope budget to a dictionary representation, including all category groups.

  • from_category –

    Returns the budget category for the given category if it exists.

Attributes:

for_next_month instance-attribute 

for_next_month: Decimal

The amount of money held for the next month.

last_month_overspent instance-attribute 

last_month_overspent: Decimal

The overspent amount from the previous month.

from_last_month instance-attribute 

from_last_month: Decimal

The amount of money inherited from the previous month.

overspent property 

overspent: Decimal

The amount of money overspent for the current month.

This is equivalent to the sum of all negative accumulated balances in all categories. Always returns a negative number (or zero if there is no overspending).

available_funds property 

available_funds: Decimal

The sum of all incomes plus the budget held from a previous month

to_budget property 

to_budget

The amount of money available for budgeting.

This is equivalent to the available funds minus the budgeted amount, minus the budget for the next month. If you had overspending from the previous month, it will also subtract from the total value.

month instance-attribute 

month: date

The month this budget applies to (always the first day of the month).

category_groups instance-attribute 

category_groups: list[BudgetCategoryGroup]

List of BudgetCategoryGroup objects containing all budget categories.

income_category_groups instance-attribute 

income_category_groups: list[IncomeCategoryGroup]

List of IncomeCategoryGroup objects containing all income categories.

received property 

received: Decimal

Total income for this month.

budgeted property 

budgeted: Decimal

The amount of money distributed on all budgets for this month.

Keep in mind that, while frontend shows this as a negative number, the budgeted amount is always positive.

accumulated_balance property 

accumulated_balance: Decimal

Sum of all balances from all categories.

spent property 

spent

Expenses for the current month.

It is the sum of all money spent on the month.

categories property 

categories: Iterator[BudgetCategory]

List all categories in this budget.

as_dict 

as_dict() -> dict

Converts the envelope budget to a dictionary representation, including all category groups.

For simplicity, both the expenses and income category groups are combined into a single list, similar to how the JS API does it.

Source code in actual/budgets.py 
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
def as_dict(self) -> dict:
    """
    Converts the envelope budget to a dictionary representation, including all category groups.

    For simplicity, both the expenses and income category groups are combined into a single list,
    similar to how the JS API does it.
    """
    # Combine expense and income category groups
    all_category_groups = [cg.as_dict() for cg in self.category_groups]
    all_category_groups.extend([cg.as_dict() for cg in self.income_category_groups])

    return {
        "month": self.month.strftime("%Y-%m"),
        "incomeAvailable": self.available_funds,
        "lastMonthOverspent": self.last_month_overspent,
        "forNextMonth": self.for_next_month,
        "totalBudgeted": self.budgeted,
        "toBudget": self.to_budget,
        "fromLastMonth": self.from_last_month,
        "totalIncome": self.received,
        "totalSpent": self.spent,
        "totalBalance": self.accumulated_balance,
        "categoryGroups": all_category_groups,
    }

from_category 

from_category(
    category: Categories,
) -> BudgetCategory | None

Returns the budget category for the given category if it exists.

Source code in actual/budgets.py 
297
298
299
300
301
302
303
def from_category(self, category: Categories) -> BudgetCategory | None:
    """Returns the budget category for the given category if it exists."""
    for group in self.category_groups:
        for cat in group.categories:
            if cat.database_object.id == category.id:
                return cat
    return None

TrackingBudget dataclass 

TrackingBudget(
    month: date,
    category_groups: list[BudgetCategoryGroup],
    income_category_groups: list[IncomeCategoryGroup],
)

Bases: BaseBudget

Budget information for tracking budgeting mode for a single month.

Tracking budgeting is an alternative budgeting mode that focuses on the simplicity of tracking expenses.

Parameters:

Methods:

  • as_dict –

    Converts the tracking budget to a dictionary representation, including all category groups.

  • from_category –

    Returns the budget category for the given category if it exists.

Attributes:

overspent property 

overspent: Decimal

The amount of money overspent for the current month.

This is equivalent to the sum of income (positive) and expenses (negative). If you end up with a positive value, you have saved money, otherwise you have overspent.

budgeted_income property 

budgeted_income: Decimal

The amount of income budgeted for the current month.

month instance-attribute 

month: date

The month this budget applies to (always the first day of the month).

category_groups instance-attribute 

category_groups: list[BudgetCategoryGroup]

List of BudgetCategoryGroup objects containing all budget categories.

income_category_groups instance-attribute 

income_category_groups: list[IncomeCategoryGroup]

List of IncomeCategoryGroup objects containing all income categories.

received property 

received: Decimal

Total income for this month.

budgeted property 

budgeted: Decimal

The amount of money distributed on all budgets for this month.

Keep in mind that, while frontend shows this as a negative number, the budgeted amount is always positive.

accumulated_balance property 

accumulated_balance: Decimal

Sum of all balances from all categories.

spent property 

spent

Expenses for the current month.

It is the sum of all money spent on the month.

categories property 

categories: Iterator[BudgetCategory]

List all categories in this budget.

as_dict 

as_dict() -> dict

Converts the tracking budget to a dictionary representation, including all category groups.

For simplicity, both the expenses and income category groups are combined into a single list, similar to how the JS API does it.

Source code in actual/budgets.py 
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
def as_dict(self) -> dict:
    """
    Converts the tracking budget to a dictionary representation, including all category groups.

    For simplicity, both the expenses and income category groups are combined into a single list,
    similar to how the JS API does it.
    """
    # Combine expense and income category groups
    all_category_groups = [cg.as_dict() for cg in self.category_groups]
    all_category_groups.extend([cg.as_dict() for cg in self.income_category_groups])

    return {
        "month": self.month.strftime("%Y-%m"),
        "totalIncome": self.received,
        "totalSpent": self.spent,
        "totalBalance": self.accumulated_balance,
        "budgeted": self.budgeted,
        "budgetedIncome": self.budgeted_income,
        "overspent": self.overspent,
        "categoryGroups": all_category_groups,
    }

from_category 

from_category(
    category: Categories,
) -> BudgetCategory | None

Returns the budget category for the given category if it exists.

Source code in actual/budgets.py 
297
298
299
300
301
302
303
def from_category(self, category: Categories) -> BudgetCategory | None:
    """Returns the budget category for the given category if it exists."""
    for group in self.category_groups:
        for cat in group.categories:
            if cat.database_object.id == category.id:
                return cat
    return None

BudgetList 

BudgetList(iterable, is_tracking_budget: bool = False)

Bases: list[EnvelopeBudget | TrackingBudget]

A list of budget objects with helper methods for accessing budget information.

This class extends the built-in list to provide convenient methods for working with multiple months of budget data.

Parameters:

  • iterable

    –

    The list of EnvelopeBudget or TrackingBudget objects.

  • is_tracking_budget

    (bool, default: False ) –

    Whether the budgets are tracking budgets (True) or envelope budgets (False).

Methods:

  • from_month –

    Returns the budget for a particular month. If missing, will return None.

Attributes:

Source code in actual/budgets.py 
437
438
439
def __init__(self, iterable, is_tracking_budget: bool = False):
    super().__init__(iterable)
    self.is_tracking_budget: bool = is_tracking_budget

total_income property 

total_income: Decimal

Returns the total income for all months in the list.

This is not a relevant metric in general as it is the simple sum of all income amounts.

total_spent property 

total_spent: Decimal

Returns the total amount spent for all months in the list.

total_budgeted property 

total_budgeted: Decimal

Returns the total budgeted for all months in the list.

This is not a relevant metric in general as it is the simple sum of all budgeted amounts.

from_month 

from_month(
    month: date,
) -> EnvelopeBudget | TrackingBudget | None

Returns the budget for a particular month. If missing, will return None.

Source code in actual/budgets.py 
466
467
468
469
470
471
472
def from_month(self, month: datetime.date) -> EnvelopeBudget | TrackingBudget | None:
    """Returns the budget for a particular month. If missing, will return None."""
    month = month.replace(day=1)
    for budget in self:
        if budget.month == month:
            return budget
    return None

get_budget_history 

get_budget_history(
    s: Session, until: date | None = None
) -> BudgetList

Returns the budget history from the first available month to the given month, as iterable.

If no month is given, the current month is used.

Example:

import datetime
from actual import Actual
from actual.budgets import get_budget_history

with Actual("http://localhost:5006", password="mypass", file="Budget") as actual:
    # get the history until the latest month
    history = get_budget_history(actual.session)
    # select the latest month
    print(history[-1])
    # If you want a similar object than the Actual JS API, you can convert it to a dictionary:
    print(history[-1].as_dict())

Parameters:

  • s

    (Session) –

    Session from the Actual local database.

  • until

    (date | None, default: None ) –

    Month to get budgets for, as a date for that month. Use datetime.date.today() if you want current data.

Source code in actual/budgets.py 
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
def get_budget_history(s: Session, until: datetime.date | None = None) -> BudgetList:
    """
    Returns the budget history from the first available month to the given month, as iterable.

    If no month is given, the current month is used.

    Example:

    ```python
    import datetime
    from actual import Actual
    from actual.budgets import get_budget_history

    with Actual("http://localhost:5006", password="mypass", file="Budget") as actual:
        # get the history until the latest month
        history = get_budget_history(actual.session)
        # select the latest month
        print(history[-1])
        # If you want a similar object than the Actual JS API, you can convert it to a dictionary:
        print(history[-1].as_dict())
    ```

    :param s: Session from the Actual local database.
    :param until: Month to get budgets for, as a date for that month. Use `datetime.date.today()` if you want current
                  data.
    """
    if until is None:
        until = datetime.date.today()
    until = until.replace(day=1)
    is_tracking_budget = _get_budget_table(s) is ReflectBudgets
    if is_tracking_budget:
        return BudgetList(_get_tracking_budget_info(s, until), is_tracking_budget=True)
    else:
        return BudgetList(_get_envelope_budget_info(s, until))