ComadClient

The top-level client. Instantiate once, call login(), then access resources through the sub-client attributes.

pycomad.ComadClient

ComadClient(api_url: str, auth_url: Optional[str] = None)

Client for the Comad Digital Asset Management (DAM) REST API.

Authentication is handled by the ullav-user-management service. Call :meth:login before making any API requests; a :exc:~pycomad.exceptions.ComadAuthError will be raised otherwise.

The JWT is stored in the session and attached to every subsequent request automatically. Tokens expire according to the server's configuration; call :meth:login again to refresh.

Parameters:

Name	Type	Description	Default
api_url	str	Base URL of the Comad DAM server, e.g. "http://localhost:8080".	required
auth_url	Optional[str]	Base URL of the authentication service, e.g. "http://localhost:8081". Defaults to api_url when both services are served behind the same proxy.	None

Example

.. code-block:: python

from pycomad import ComadClient

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

# Upload a file
asset = client.assets.upload("photo.jpg", creator="colin")

# Search by location
results = client.search.nearby(lat=53.3, lon=-6.2, radius_km=5)

# Categories
cats = client.categories.list()
cat = client.categories.create("Architecture", access_level="Global")
client.assets.add_category(asset.id, cat.id)

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

api_url property

api_url: str

Base URL of the DAM server.

token property

token: Optional[str]

The JWT in use (after :meth:login or :meth:set_token).

download_url

download_url(asset_id: Union[UUID, str]) -> str

URL of an asset's primary file (supports Range; send Authorization: Bearer <token>).

Lets tools such as ffmpeg read large files directly instead of downloading them whole.

set_token

set_token(token: str) -> None

Use an existing JWT instead of calling :meth:login.

For workers that are handed a token (for example an Obair automated task that receives the initiating user's token as a secret) and must act as that user. The token is attached to every subsequent request; it is not validated here.

login

login(email: str, password: str) -> LoginInfo

Authenticate and store the JWT for subsequent requests.

Parameters:

Name	Type	Description	Default
email	str	User email address.	required
password	str	User password.	required

Returns:

Type	Description
LoginInfo	class:~pycomad.models.LoginInfo containing the token, user
LoginInfo	details, roles, and permissions.

Raises:

Type	Description
ComadAuthError	If the credentials are invalid.