budgero 0.1.3

Official Python SDK for Budgero - Privacy-First Zero Based Budget Manager

Budgero Python SDK

Official Python SDK for Budgero - Privacy-First Zero Based Budget Manager.

Installation

pip install budgero

Quick Start

from budgero import BudgeroClient

# Initialize the client with your API key and encryption key
client = BudgeroClient(
    api_key="your-api-key",
    encryption_key="your-encryption-key",
)

# Add a transaction
result = client.add_transaction(
    account_id=1,
    category_id=5,
    budget_id=1,
    date="2024-11-27",
    outflow=50.00,
    memo="Weekly groceries",
    payee="Whole Foods",
)

print(f"Transaction queued: {result.queue_id}")

Getting Your Credentials

1. Open the Budgero app
2. Go to Settings > Integrations > Push API
3. Generate a new API key
4. Copy both the API key and encryption key

Features

• End-to-end encryption: All transaction data is encrypted client-side before being sent to the server
• Type-safe: Full type hints for IDE autocompletion and type checking
• Simple API: Easy-to-use methods for common operations
• Self-hosted support: Works with self-hosted Budgero instances

Usage Examples

Record an Expense

client.add_transaction(
    account_id=1,
    category_id=5,  # Groceries
    budget_id=1,
    date="2024-11-27",
    outflow=50.00,
    memo="Weekly groceries",
    payee="Whole Foods",
)

Record Income

from datetime import date

client.add_transaction(
    account_id=1,
    category_id=10,  # Income category
    budget_id=1,
    date=date.today(),
    inflow=3000.00,
    memo="Monthly salary",
    payee="Acme Corp",
)

Using Context Manager

from budgero import BudgeroClient

with BudgeroClient(api_key="...", encryption_key="...") as client:
    client.add_transaction(
        account_id=1,
        category_id=5,
        budget_id=1,
        date="2024-11-27",
        outflow=25.00,
        memo="Coffee",
    )
# Client is automatically closed

Check Queue Status

# Get pending items
queue = client.get_queue()
for item in queue:
    print(f"{item.id}: {item.status}")

# Get statistics
stats = client.get_queue_stats()
print(f"Pending: {stats['pending']}")

Self-Hosted Instance

client = BudgeroClient(
    api_key="your-api-key",
    encryption_key="your-encryption-key",
    base_url="https://budgero.mycompany.com",
)

API Reference

BudgeroClient

__init__(api_key, encryption_key, *, base_url, timeout)

Initialize the client.

• api_key: Your Budgero Push API key
• encryption_key: Your encryption key (hex or base64 format)
• base_url: API base URL (default: https://my.budgero.app)
• timeout: Request timeout in seconds (default: 30)

add_transaction(...)

Add a new transaction to your budget.

• account_id: ID of the account
• category_id: ID of the category (None for transfers)
• budget_id: ID of the budget
• date: Transaction date (string or date object)
• inflow: Amount flowing in (default: 0)
• outflow: Amount flowing out (default: 0)
• memo: Description (default: "")
• payee: Payee name (optional)
• transfer_id: Transfer ID for linked transfers (optional)

get_queue()

Get pending items in the push queue.

get_queue_stats()

Get statistics about the push queue.

clear_queue()

Clear all items from the push queue.

health_check()

Check if the API is healthy.

close()

Close the client and release resources.

Data Models

TransactionInput

from budgero import TransactionInput

tx = TransactionInput(
    account_id=1,
    category_id=5,
    budget_id=1,
    date="2024-11-27",
    inflow=0.0,
    outflow=50.00,
    memo="Groceries",
    payee="Store",
)

Error Handling

from budgero import BudgeroClient, AuthenticationError, APIError, ValidationError

try:
    client.add_transaction(...)
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Invalid input: {e}")
except APIError as e:
    print(f"API error: {e} (HTTP {e.status_code})")

Requirements

• Python 3.9+
• httpx
• pycryptodome

License

MIT