Assets

Accessed via client.assets.

pycomad.client.AssetsClient

AssetsClient(http: _HttpSession)

Methods for the /assets resource.

list

list() -> List[Asset]

Return all assets visible to the authenticated user.

Returns:

Type	Description
List[Asset]	List of :class:~pycomad.models.Asset objects.

Raises:

Type	Description
ComadAuthError	If not authenticated.

create

create(name: str, asset_type: str, *, description: Optional[str] = None, caption: Optional[str] = None, keywords: Optional[str] = None, creator: Optional[str] = None, copyright_notice: Optional[str] = None, available: Optional[bool] = None, available_until: Optional[datetime] = None, is_locked: Optional[bool] = None, is_private: Optional[bool] = None, public_read: Optional[bool] = None, public_download: Optional[bool] = None, public_write: Optional[bool] = None, team_id: Optional[str] = None, custom_fields: Optional[Dict[str, Any]] = None) -> Asset

Create an asset record without uploading a file.

Use :meth:upload to create an asset and upload the file in one step.

Parameters:

Name	Type	Description	Default
name	str	Asset name.	required
asset_type	str	MIME type (e.g. "image/png").	required
description	Optional[str]	Free-text description.	None
caption	Optional[str]	Display caption.	None
keywords	Optional[str]	Comma-separated keywords.	None
creator	Optional[str]	Author / creator name.	None
copyright_notice	Optional[str]	Copyright string.	None
available	Optional[bool]	Whether the asset is publicly available (default True).	None
available_until	Optional[datetime]	Expiry datetime; the asset becomes unavailable after this.	None
is_locked	Optional[bool]	Locked assets cannot be deleted (default False).	None
is_private	Optional[bool]	Private to the uploader (default True).	None
public_read	Optional[bool]	Allow unauthenticated read (default False).	None
public_download	Optional[bool]	Allow unauthenticated download (default False).	None
public_write	Optional[bool]	Allow unauthenticated write (default False).	None
team_id	Optional[str]	Team to assign this asset to.	None
custom_fields	Optional[Dict[str, Any]]	Arbitrary key/value pairs for team-defined custom fields.	None

Returns:

Type	Description
Asset	The newly created :class:~pycomad.models.Asset.

Raises:

Type	Description
ComadAuthError	If not authenticated.
ComadValidationError	On a 400 response.

upload

upload(file: FileArg, *, name: Optional[str] = None, asset_type: Optional[str] = None, description: Optional[str] = None, caption: Optional[str] = None, keywords: Optional[str] = None, creator: Optional[str] = None, copyright_notice: Optional[str] = None, available: Optional[bool] = None, available_until: Optional[datetime] = None, is_locked: Optional[bool] = None, is_private: Optional[bool] = None, public_read: Optional[bool] = None, public_download: Optional[bool] = None, public_write: Optional[bool] = None, team_id: Optional[str] = None, custom_fields: Optional[Dict[str, Any]] = None) -> Asset

Create an asset record and upload the file in a single request.

Parameters:

Name	Type	Description	Default
file	FileArg	File to upload — a path string, :class:~pathlib.Path, or an open binary file object.	required
name	Optional[str]	Asset name; defaults to the filename if omitted.	None
asset_type	Optional[str]	MIME type; inferred from the file extension if omitted.	None
description	Optional[str]	Free-text description.	None
caption	Optional[str]	Display caption.	None
keywords	Optional[str]	Comma-separated keywords.	None
creator	Optional[str]	Author / creator name.	None
copyright_notice	Optional[str]	Copyright string.	None
available	Optional[bool]	Whether the asset is publicly available (default True).	None
available_until	Optional[datetime]	Expiry datetime (timezone-aware recommended).	None
is_locked	Optional[bool]	Locked assets cannot be deleted (default False).	None
is_private	Optional[bool]	Private to the uploader (default True).	None
public_read	Optional[bool]	Allow unauthenticated read (default False).	None
public_download	Optional[bool]	Allow unauthenticated download (default False).	None
public_write	Optional[bool]	Allow unauthenticated write (default False).	None
team_id	Optional[str]	Team to assign this asset to.	None
custom_fields	Optional[Dict[str, Any]]	Arbitrary key/value pairs for team-defined custom fields.	None

Returns:

Type	Description
Asset	The newly created :class:~pycomad.models.Asset.

Raises:

Type	Description
ComadAuthError	If not authenticated.
ComadValidationError	On a 400 response (e.g. missing required file).

get

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

Fetch an asset with its associated categories.

Parameters:

Name	Type	Description	Default
asset_id	Union[UUID, str]	UUID of the asset.	required

Returns:

Type	Description
AssetWithCategories	class:~pycomad.models.AssetWithCategories.

Raises:

Type	Description
ComadNotFoundError	If the asset does not exist.
ComadAuthError	If not authenticated.

update

update(asset_id: Union[UUID, str], *, name: Optional[str] = None, asset_type: Optional[str] = None, description: Optional[str] = None, caption: Optional[str] = None, keywords: Optional[str] = None, creator: Optional[str] = None, copyright_notice: Optional[str] = None, available: Optional[bool] = None, available_until: Optional[datetime] = None, is_locked: Optional[bool] = None, is_private: Optional[bool] = None, public_read: Optional[bool] = None, public_download: Optional[bool] = None, public_write: Optional[bool] = None, team_id: Optional[str] = None, custom_fields: Optional[Dict[str, Any]] = None) -> Asset

Update asset metadata; only supplied fields are changed.

Parameters:

Name	Type	Description	Default
asset_id	Union[UUID, str]	UUID of the asset to update.	required
name	Optional[str]	New name.	None
asset_type	Optional[str]	New MIME type.	None
description	Optional[str]	New description.	None
caption	Optional[str]	New caption.	None
keywords	Optional[str]	New keywords.	None
creator	Optional[str]	New creator.	None
copyright_notice	Optional[str]	New copyright notice.	None
available	Optional[bool]	New availability flag.	None
available_until	Optional[datetime]	New expiry datetime.	None
is_locked	Optional[bool]	New locked flag.	None
is_private	Optional[bool]	New private flag.	None
public_read	Optional[bool]	New public-read flag.	None
public_download	Optional[bool]	New public-download flag.	None
public_write	Optional[bool]	New public-write flag.	None
team_id	Optional[str]	Reassign to a different team.	None
custom_fields	Optional[Dict[str, Any]]	New custom field values (replaces existing).	None

Returns:

Type	Description
Asset	The updated :class:~pycomad.models.Asset.

Raises:

Type	Description
ComadNotFoundError	If the asset does not exist.
ComadAuthError	If not authenticated.

delete

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

Delete an asset and remove its file from storage.

Parameters:

Name	Type	Description	Default
asset_id	Union[UUID, str]	UUID of the asset to delete.	required

Raises:

Type	Description
ComadAuthError	If not authenticated or the asset is locked (403).
ComadNotFoundError	If the asset does not exist.

upload_file

upload_file(asset_id: Union[UUID, str], file: FileArg) -> Asset

Upload (or replace) the file attached to an existing asset record.

Parameters:

Name	Type	Description	Default
asset_id	Union[UUID, str]	UUID of the asset.	required
file	FileArg	File to upload — a path string, :class:~pathlib.Path, or an open binary file object.	required

Returns:

Type	Description
Asset	The updated :class:~pycomad.models.Asset.

Raises:

Type	Description
ComadNotFoundError	If the asset does not exist.
ComadAuthError	If not authenticated.

download

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

Download the raw file bytes for an asset.

Parameters:

Name	Type	Description	Default
asset_id	Union[UUID, str]	UUID of the asset.	required

Returns:

Type	Description
bytes	Raw file bytes.

Raises:

Type	Description
ComadNotFoundError	If the asset does not exist.
ComadAuthError	If not authenticated.

thumbnail

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

Fetch a thumbnail for an asset.

For images, PDFs, and Office/iWork documents, returns a PNG image. For all other types, returns an SVG icon.

Parameters:

Name	Type	Description	Default
asset_id	Union[UUID, str]	UUID of the asset.	required

Returns:

Type	Description
bytes	Raw image bytes (PNG or SVG).

Raises:

Type	Description
ComadNotFoundError	If the asset does not exist.
ComadAuthError	If not authenticated.

add_category

add_category(asset_id: Union[UUID, str], category_id: Union[UUID, str]) -> None

Add a category to an asset.

Parameters:

Name	Type	Description	Default
asset_id	Union[UUID, str]	UUID of the asset.	required
category_id	Union[UUID, str]	UUID of the category to add.	required

Raises:

Type	Description
ComadAuthError	If not authenticated.

remove_category

remove_category(asset_id: Union[UUID, str], category_id: Union[UUID, str]) -> None

Remove a category from an asset.

Parameters:

Name	Type	Description	Default
asset_id	Union[UUID, str]	UUID of the asset.	required
category_id	Union[UUID, str]	UUID of the category to remove.	required

Raises:

Type	Description
ComadAuthError	If not authenticated.

usage

usage() -> UsageSummary

Return current storage usage and plan limits for the authenticated user.

Returns:

Type	Description
UsageSummary	class:~pycomad.models.UsageSummary.

Raises:

Type	Description
ComadAuthError	If not authenticated or the user has no DAM access.