Python SDK

The official Python SDK provides type hints, async support, and convenient methods for all API operations.

Installation

pip install mando-sdk

Or with Poetry:

poetry add mando-sdk

Requirements

• Python 3.9+
• httpx for HTTP requests
• pydantic for data validation

Quick Start

import os
from mando_sdk import MandoClient

client = MandoClient(
    api_key=os.environ["MANDO_API_KEY"],
    base_url="https://www.mando.fi/api"  # optional, this is the default
)

# List all products
products = client.plu.list()
print(products.data)

Configuration

client = MandoClient(
    # Required
    api_key="your-api-key",

    # Optional
    base_url="https://www.mando.fi/api",
    timeout=30.0,  # 30 seconds
    retries=3,
    retry_delay=1.0,  # 1 second base delay
)

CRUD Operations

List Entities

# List all products
products = client.plu.list()

# With pagination
page = client.plu.list(page=1, page_size=50)

# With filters
active = client.plu.list(active=True, group_id="beverages")

Get Single Entity

product = client.plu.get("550e8400-e29b-41d4-a716-446655440000")
print(product.data.name)

Create Entity

new_product = client.plu.create({
    "name": "Espresso",
    "price": 3.50,
    "group_id": "beverages",
    "tax_id": "standard-vat"
})
print(new_product.data.id)

Update Entity

updated = client.plu.update("product-id", {
    "price": 4.00,
    "active": True
})

Error Handling

from mando_sdk import MandoClient, MandoError
import time

try:
    product = client.plu.get("invalid-id")
except MandoError as e:
    print(f"Error {e.status}: {e.message}")
    print(f"Code: {e.code}")

    # Handle specific errors
    if e.status == 404:
        print("Product not found")
    elif e.status == 429:
        # Rate limited - retry after delay
        retry_after = e.retry_after or 60
        print(f"Rate limited. Retry after {retry_after} seconds")
        time.sleep(retry_after)

Pagination Helper

Iterate through all pages automatically:

# Generator for all products
for product in client.plu.list_all():
    print(product.name)

# Or collect all at once
all_products = list(client.plu.list_all())

Type Hints

All responses have full type hints:

from mando_sdk import MandoClient
from mando_sdk.models import Plu, Customer, Sale

def get_product_names(client: MandoClient) -> list[str]:
    response = client.plu.list()
    return [plu.name for plu in response.data]

Async Support

Use the async client for better performance:

import asyncio
from mando_sdk import AsyncMandoClient

async def main():
    client = AsyncMandoClient(
        api_key=os.environ["MANDO_API_KEY"]
    )

    # Async operations
    products = await client.plu.list()
    print(products.data)

    # Concurrent requests
    product1, product2 = await asyncio.gather(
        client.plu.get("id-1"),
        client.plu.get("id-2")
    )

asyncio.run(main())

Context Manager

Use as a context manager for automatic cleanup:

from mando_sdk import MandoClient

with MandoClient(api_key="your-key") as client:
    products = client.plu.list()
    # Connection is automatically closed when exiting the block

Or with async:

async with AsyncMandoClient(api_key="your-key") as client:
    products = await client.plu.list()

Advanced Usage

Custom Headers

client = MandoClient(
    api_key="your-key",
    headers={
        "X-Custom-Header": "value"
    }
)

Request Hooks

def log_request(request):
    print(f"Making request to {request.url}")
    return request

def log_response(response):
    print(f"Received {response.status_code}")
    return response

client = MandoClient(
    api_key="your-key",
    request_hook=log_request,
    response_hook=log_response
)

Timeout per Request

# Override timeout for a single request
products = client.plu.list(timeout=60.0)

Example: Export Sales Report

import os
import csv
from datetime import date, timedelta
from mando_sdk import MandoClient

def export_weekly_sales():
    client = MandoClient(
        api_key=os.environ["MANDO_API_KEY"]
    )

    # Get last week's sales
    end_date = date.today()
    start_date = end_date - timedelta(days=7)

    sales = list(client.sales.list_all(
        from_date=start_date.isoformat(),
        to_date=end_date.isoformat()
    ))

    # Export to CSV
    with open("weekly_sales.csv", "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=["id", "date", "total", "items"])
        writer.writeheader()
        for sale in sales:
            writer.writerow({
                "id": sale.id,
                "date": sale.created_at,
                "total": sale.total,
                "items": len(sale.items)
            })

    print(f"Exported {len(sales)} sales to weekly_sales.csv")

if __name__ == "__main__":
    export_weekly_sales()

Example: Bulk Update

import os
from mando_sdk import MandoClient

def increase_prices(percentage: float):
    client = MandoClient(
        api_key=os.environ["MANDO_API_KEY"]
    )

    updated_count = 0
    for product in client.plu.list_all(active=True):
        new_price = round(product.price * (1 + percentage / 100), 2)
        client.plu.update(product.id, {"price": new_price})
        updated_count += 1
        print(f"Updated {product.name}: {product.price} -> {new_price}")

    print(f"Updated {updated_count} products")

if __name__ == "__main__":
    increase_prices(5.0)  # Increase all prices by 5%