Assets

Accessed via client.assets.

pycomad.client.AssetsClient

AssetsClient(http: _HttpSession)

Methods for the /assets resource.

list

list(*, category_id: Optional[Union[UUID, str]] = None, q: Optional[str] = None, my_assets: Optional[bool] = None, sort_field: Optional[str] = None, sort_dir: Optional[str] = None, page: Optional[int] = None, per_page: Optional[int] = None, uncategorised: Optional[bool] = None, asset_type: Optional[str] = None, kind: Optional[str] = None) -> AssetPage

Return one page of the assets visible to the authenticated user.

The server paginates; the returned :class:~pycomad.models.AssetPage can be iterated and indexed like a list of the page's items, and has total / has_more. Use :meth:list_all to walk every page.

Parameters:

Name	Type	Description	Default
category_id	Optional[Union[UUID, str]]	Only assets in this category.	None
q	Optional[str]	Substring search across name, caption, description, keywords and creator.	None
my_assets	Optional[bool]	Only assets you own.	None
sort_field	Optional[str]	"name", "asset_type", "size" or "created_at" (default).	None
sort_dir	Optional[str]	"asc" or "desc" (default).	None
page	Optional[int]	1-based page number (default 1).	None
per_page	Optional[int]	Items per page, 1-200 (default 20).	None
uncategorised	Optional[bool]	Only assets with no category.	None
asset_type	Optional[str]	Only MIME types starting with this prefix, e.g. "image/".	None
kind	Optional[str]	Comma-separated groups: image, video, audio, model, document, other.	None

Raises:

Type	Description
ComadAuthError	If not authenticated.
ComadValidationError	On an unknown kind.

list_all

list_all(*, category_id: Optional[Union[UUID, str]] = None, q: Optional[str] = None, my_assets: Optional[bool] = None, sort_field: Optional[str] = None, sort_dir: Optional[str] = None, per_page: int = 200, uncategorised: Optional[bool] = None, asset_type: Optional[str] = None, kind: Optional[str] = None) -> Iterator[AssetWithCategories]

Iterate over every matching asset, fetching pages as needed (same filters as :meth:list).

geotagged

geotagged(*, lat_min: Optional[float] = None, lat_max: Optional[float] = None, lon_min: Optional[float] = None, lon_max: Optional[float] = None, category_id: Optional[Union[UUID, str]] = None) -> List[GeoAsset]

Return GPS pins for geotagged assets (for map views), optionally within a bounding box.

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, ocr_text: Optional[str] = None, artwork_artist: Optional[str] = None, artwork_date: Optional[str] = None, artwork_location: Optional[str] = None, artwork_owner: Optional[str] = None, artwork_medium: Optional[str] = None, artwork_dimensions: Optional[str] = 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
ocr_text	Optional[str]	Replace the OCR text.	None
artwork_artist	Optional[str]	The artwork's artist.	None
artwork_date	Optional[str]	Fuzzy date of the artwork: a year, decade, approximation or range.	None
artwork_location	Optional[str]	Where the artwork is.	None
artwork_owner	Optional[str]	Who owns the artwork.	None
artwork_medium	Optional[str]	Medium, e.g. "oil on canvas".	None
artwork_dimensions	Optional[str]	Dimensions as free text.	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.

set_thumbnail

set_thumbnail(asset_id: Union[UUID, str], image: Union[bytes, str, Path], *, content_type: str = 'image/png') -> None

Set a custom thumbnail (owner/admin only).

3D models cannot be rendered by the server, so a worker that renders one uploads the picture here. The server validates it (PNG, JPEG or WebP, at most 4096 px a side) and stores a PNG of at most THUMBNAIL_SIZE.

Parameters:

Name	Type	Description	Default
asset_id	Union[UUID, str]	UUID of the asset.	required
image	Union[bytes, str, Path]	Image bytes, or a path to an image file.	required
content_type	str	MIME type of image (default image/png).	'image/png'

Raises:

Type	Description
ComadValidationError	If the image is invalid.
ComadAuthError	If not authenticated or not the owner.
ComadNotFoundError	If the asset does not exist.

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.