pycomad

Python client library for the Comad DAM (Digital Asset Management) API.

Installation

pip install pycomad

Requires Python 3.9+.

Quick start

from pycomad import ComadClient

client = ComadClient(
    api_url="http://localhost:8080",
    auth_url="http://localhost:8081",   # ullav-user-management service
)
client.login(email="user@example.com", password="secret")

# Upload a file (creates the record and uploads in one step)
asset = client.assets.upload("photo.jpg", creator="alice", is_private=False)

# Download and generate a thumbnail
raw_bytes = client.assets.download(asset.id)
thumb_png  = client.assets.thumbnail(asset.id)

# Categories
cat = client.categories.create("Architecture", access_level="Global")
client.assets.add_category(asset.id, cat.id)
detail = client.assets.get(asset.id)   # AssetWithCategories

# Search
results = client.search.search(q="photo", creator="alice")
nearby  = client.search.nearby(lat=53.3, lon=-6.2, radius_km=5)

# Metadata (EXIF / IPTC / XMP)
meta = client.metadata.get(asset.id)
if meta.exif:
    print(meta.exif.get("camera_make"))

# Usage quotas
usage = client.assets.usage()
print(f"{usage.asset_count} assets, {usage.used_bytes // 1024**2} MB used")

# ZIP batch import
result = client.zip.upload("photos.zip", creator="alice")
print(f"Imported {len(result.assets)} assets into {len(result.categories)} categories")

Authentication

ComadClient authenticates against the ullav-user-management service (which issues the JWT accepted by the Comad DAM server).

# Same host (auth behind the same reverse proxy)
client = ComadClient("https://dam.example.com")
client.login(email="user@example.com", password="secret")

# Separate auth host
client = ComadClient(
    api_url="https://dam.example.com",
    auth_url="https://auth.example.com",
)
client.login(email="user@example.com", password="secret")

Error handling

All exceptions inherit from ComadError:

from pycomad import ComadClient, ComadNotFoundError, ComadAuthError

try:
    asset = client.assets.get(some_id)
except ComadNotFoundError:
    print("Asset not found")
except ComadAuthError:
    print("Not logged in or session expired")

Exception	Raised when
ComadAuthError	login() not called; 401 or 403 response
ComadNotFoundError	404 — resource does not exist
ComadValidationError	400 — invalid input
ComadServerError	5xx — server-side fault
ComadError	Base class; catches all of the above