cloudinary 1.46.3__tar.gz → 1.47.0__tar.gz

{cloudinary-1.46.3/cloudinary.egg-info → cloudinary-1.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloudinary
-Version: 1.46.3
+Version: 1.47.0
 Summary: Upload, transform, optimize, and manage images and videos with Cloudinary from Python or Django.
 Author-email: Cloudinary <info@cloudinary.com>
 License: MIT License
@@ -142,6 +142,7 @@ Save as `quickstart.py` and run `python quickstart.py`. [Create a free account](
 - [Transform and deliver an image](cloudinary/docs/transform-and-deliver-image.md)
 - [Transform and deliver a video](cloudinary/docs/transform-and-deliver-video.md)
 - [Search and manage assets](cloudinary/docs/search-and-manage-assets.md)
+- [Organize and share collections](cloudinary/docs/organize-and-share-collections.md)
 - [Moderate an upload](cloudinary/docs/moderate-upload.md)
 - [Use structured metadata](cloudinary/docs/use-structured-metadata.md)
 - [Use with Django](cloudinary/docs/use-with-django.md)

{cloudinary-1.46.3 → cloudinary-1.47.0}/README.md

@@ -71,6 +71,7 @@ Save as `quickstart.py` and run `python quickstart.py`. [Create a free account](
 - [Transform and deliver an image](cloudinary/docs/transform-and-deliver-image.md)
 - [Transform and deliver a video](cloudinary/docs/transform-and-deliver-video.md)
 - [Search and manage assets](cloudinary/docs/search-and-manage-assets.md)
+- [Organize and share collections](cloudinary/docs/organize-and-share-collections.md)
 - [Moderate an upload](cloudinary/docs/moderate-upload.md)
 - [Use structured metadata](cloudinary/docs/use-structured-metadata.md)
 - [Use with Django](cloudinary/docs/use-with-django.md)

{cloudinary-1.46.3 → cloudinary-1.47.0}/cloudinary/__init__.py

@@ -38,7 +38,7 @@ CL_BLANK = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAA
 URI_SCHEME = "cloudinary"
 API_VERSION = "v1_1"
 
-VERSION = "1.46.3"
+VERSION = "1.47.0"
 
 _USER_PLATFORM_DETAILS = "; ".join((platform(), "Python {}".format(python_version())))
 

{cloudinary-1.46.3 → cloudinary-1.47.0}/cloudinary/api_client/execute_request.py

@@ -7,11 +7,14 @@ from urllib3.exceptions import HTTPError
 
 import cloudinary
 from cloudinary.exceptions import (
+    Error,
     BadRequest,
     AuthorizationRequired,
     NotAllowed,
     NotFound,
+    NotAcceptable,
     AlreadyExists,
+    Locked,
     RateLimited,
     GeneralError
 )
@@ -23,8 +26,10 @@ EXCEPTION_CODES = {
     401: AuthorizationRequired,
     403: NotAllowed,
     404: NotFound,
+    406: NotAcceptable,
     409: AlreadyExists,
     420: RateLimited,
+    423: Locked,
     429: RateLimited,
     500: GeneralError,
     503: GeneralError
@@ -88,8 +93,11 @@ def execute_request(http_connector, method, params, headers, auth, api_url, **op
         # Error is parsing json
         raise GeneralError("Error parsing server response (%d) - %s. Got - %s" % (response.status, body, e))
 
+    if response.status >= 400 and "error" not in result and "message" in result:
+        result = {"error": {"message": result["message"]}}
+
     if "error" in result:
-        exception_class = EXCEPTION_CODES.get(response.status) or Exception
+        exception_class = EXCEPTION_CODES.get(response.status) or Error
         raise exception_class("Error {0} - {1}".format(response.status, result["error"]["message"]))
 
     return Response(result, response)

cloudinary-1.47.0/cloudinary/collections.py

@@ -0,0 +1,289 @@
+# Copyright Cloudinary
+
+import json
+
+from six import string_types
+
+import cloudinary
+from cloudinary.api import only
+from cloudinary.api_client.call_api import _call_v2_api
+from cloudinary.utils import base64url_decode
+
+CUSTOMER_ID_HEADER = "X-Cld-Customer-External-Id"
+
+__COLLECTION_PARAMS = ["name", "description", "configuration"]
+
+__PUBLIC_PAGE_PARAMS = ["name", "available_from", "expires_at", "show_download_original_option",
+                        "download_transformations", "create_download_transformations"]
+
+__PUBLIC_PAGE_UPDATE_PARAMS = __PUBLIC_PAGE_PARAMS + ["protection_mode", "allowed_emails", "allowed_domains",
+                                                      "allow_any", "custom_layout_url"]
+
+
+def collections(**options):
+    """
+    Lists the collections the caller may read, most-recently-updated first by default.
+
+    :param options: Additional options.
+    :keyword str query: Case-insensitive filter on the collection name. Matches collections with a
+                        word in their name that starts with this text.
+    :keyword str sort_by: Sort expression, "<field> <direction>", optionally comma-separated.
+                          Field is one of "name", "created_at" or "updated_at"; direction is "asc"
+                          or "desc". Defaults to "updated_at desc".
+    :keyword int max_results: Maximum number of collections to return. 1-100, default 20.
+    :keyword str next_cursor: The cursor from a previous response, to fetch the next page.
+    :return: The collections, as {"data": [...], "next_cursor": ...}.
+    :rtype: Response
+    """
+    params = only(options, "query", "sort_by", "max_results", "next_cursor")
+    return __call_collections_api("get", [], params, **options)
+
+
+def create_collection(name, **options):
+    """
+    Creates a collection and makes the caller its owner.
+
+    :param name: The name of the collection.
+    :type name: str
+    :param options: Additional options.
+    :keyword str description: The description of the collection.
+    :keyword str type: "manual" (the default) holds an explicit asset list, populated with
+                       `add_collection_assets`; "dynamic" is populated by a saved search expression.
+    :keyword dict configuration: The configuration of a dynamic collection, as
+                                 {"expression": "<search expression>"}. Required for "dynamic",
+                                 not allowed for "manual".
+    :return: The created collection.
+    :rtype: Response
+    """
+    params = only(options, "description", "type", "configuration")
+    params["name"] = name
+    return __call_collections_api("post", [], params, **options)
+
+
+def collection(collection_id, **options):
+    """
+    Returns a single collection.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param options: Additional options.
+    :return: The collection.
+    :rtype: Response
+    """
+    return __call_collections_api("get", [collection_id], {}, **options)
+
+
+def update_collection(collection_id, **options):
+    """
+    Updates a collection. Only the fields passed are changed. The type of a collection can't be changed.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param options: Additional options.
+    :keyword str name: The new name of the collection.
+    :keyword str description: The new description of the collection.
+    :keyword dict configuration: The new configuration of a dynamic collection, as
+                                 {"expression": "<search expression>"}.
+    :return: The updated collection.
+    :rtype: Response
+    """
+    params = only(options, *__COLLECTION_PARAMS)
+    return __call_collections_api("put", [collection_id], params, **options)
+
+
+def delete_collection(collection_id, **options):
+    """
+    Deletes a collection. The assets in it are not modified or deleted.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param options: Additional options.
+    :return: A dictionary with a "message" key.
+    :rtype: Response
+    """
+    return __call_collections_api("delete", [collection_id], {}, **options)
+
+
+def collection_assets(collection_id, **options):
+    """
+    Lists the assets in a collection that the caller may view, newest first by default.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param options: Additional options.
+    :keyword str sort_by: Sort expression, "<field> <direction>", optionally comma-separated.
+                          Field is one of "created_at", "uploaded_at", "public_id", "display_name"
+                          or "bytes"; direction is "asc" or "desc". Defaults to "created_at desc".
+                          Send the same sort_by on every page.
+    :keyword int max_results: Maximum number of assets to return. 1-100, default 20.
+    :keyword str next_cursor: The cursor from a previous response, to fetch the next page.
+    :return: The assets, as {"data": [...], "next_cursor": ...}.
+    :rtype: Response
+    """
+    params = only(options, "sort_by", "max_results", "next_cursor")
+    return __call_collections_api("get", [collection_id, "assets"], params, **options)
+
+
+def add_collection_assets(collection_id, asset_ids, **options):
+    """
+    Adds assets to a collection.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param asset_ids: The asset IDs of the assets to add. A single ID may be passed as a string.
+    :type asset_ids: list[str] or str
+    :param options: Additional options.
+    :return: The collection.
+    :rtype: Response
+    """
+    return __call_collections_api("post", [collection_id, "assets"], __asset_ids_list(asset_ids), **options)
+
+
+def remove_collection_assets(collection_id, asset_ids, **options):
+    """
+    Removes assets from a collection. Assets not in the collection are ignored, and the assets
+    themselves are not modified or deleted.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param asset_ids: The asset IDs of the assets to remove. A single ID may be passed as a string.
+    :type asset_ids: list[str] or str
+    :param options: Additional options.
+    :return: The collection.
+    :rtype: Response
+    """
+    return __call_collections_api("delete", [collection_id, "assets"], __asset_ids_list(asset_ids), **options)
+
+
+def create_collection_public_page(collection_id, **options):
+    """
+    Publishes a collection as a shareable public page.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param options: Additional options.
+    :keyword str name: The name of the public page.
+    :keyword str available_from: The date-time (ISO 8601) the page becomes available.
+    :keyword str expires_at: The date-time (ISO 8601) the page expires.
+    :keyword bool show_download_original_option: Whether viewers can download the original assets.
+    :keyword list download_transformations: Named transformations viewers can apply when downloading,
+                                            as [{"name": "<name>", "types": ["image", ...]}, ...].
+                                            At most 200.
+    :keyword bool create_download_transformations: Whether to create any listed transformation name
+                                                   that isn't a transformation template yet.
+    :return: The created public page, including its URL.
+    :rtype: Response
+    """
+    params = only(options, *__PUBLIC_PAGE_PARAMS)
+    return __call_collections_api("post", [collection_id, "public_pages"], params, **options)
+
+
+def collection_public_pages(collection_id, **options):
+    """
+    Lists the public pages of a collection.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param options: Additional options.
+    :return: The public pages, as {"data": [...]}.
+    :rtype: Response
+    """
+    return __call_collections_api("get", [collection_id, "public_pages"], {}, **options)
+
+
+def collection_public_page(collection_id, public_page_id, **options):
+    """
+    Returns a single public page of a collection.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param public_page_id: The external ID of the public page.
+    :type public_page_id: str
+    :param options: Additional options.
+    :return: The public page.
+    :rtype: Response
+    """
+    return __call_collections_api("get", [collection_id, "public_pages", public_page_id], {}, **options)
+
+
+def update_collection_public_page(collection_id, public_page_id, **options):
+    """
+    Updates the settings of a public page of a collection.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param public_page_id: The external ID of the public page.
+    :type public_page_id: str
+    :param options: Additional options. Accepts the keywords of `create_collection_public_page`, and:
+    :keyword str protection_mode: "none" or "email_otp". "email_otp" requires the secured-sharing
+                                  feature on the plan.
+    :keyword list allowed_emails: The emails allowed to open a protected page.
+    :keyword list allowed_domains: The email domains allowed to open a protected page.
+    :keyword bool allow_any: Whether any email may open a protected page.
+    :keyword str custom_layout_url: The URL of a custom layout for the page.
+    :return: The updated public page.
+    :rtype: Response
+    """
+    params = only(options, *__PUBLIC_PAGE_UPDATE_PARAMS)
+    return __call_collections_api("put", [collection_id, "public_pages", public_page_id], params, **options)
+
+
+def delete_collection_public_page(collection_id, public_page_id, **options):
+    """
+    Unpublishes a public page of a collection. The collection and its assets are not changed.
+
+    :param collection_id: The external ID of the collection.
+    :type collection_id: str
+    :param public_page_id: The external ID of the public page.
+    :type public_page_id: str
+    :param options: Additional options.
+    :return: A dictionary with a "message" key.
+    :rtype: Response
+    """
+    return __call_collections_api("delete", [collection_id, "public_pages", public_page_id], {}, **options)
+
+
+def __asset_ids_list(asset_ids):
+    """
+    Wraps a single asset ID in a list.
+
+    :internal
+    """
+    return [asset_ids] if isinstance(asset_ids, string_types) else list(asset_ids)
+
+
+def __call_collections_api(method, uri, params, **options):
+    """
+    Private function that assists with performing an API call to the collections endpoints.
+
+    :param method: The HTTP method. Valid methods: get, post, put, delete
+    :param uri: REST endpoint of the API (without 'collections', the module or the cloud name)
+    :param params: Query/body parameters passed to the method
+    :param options: Additional options
+    :rtype: Response
+    :internal
+    """
+    oauth_token = options.get("oauth_token", cloudinary.config().oauth_token)
+    customer_id = __customer_external_id(oauth_token) if oauth_token else None
+    if customer_id:
+        extra_headers = {CUSTOMER_ID_HEADER: customer_id}
+        extra_headers.update(options.get("extra_headers") or {})
+        options["extra_headers"] = extra_headers
+
+    return _call_v2_api(method, ["collections"] + uri, params, module="asset_management", **options)
+
+
+def __customer_external_id(oauth_token):
+    """
+    Reads ext.customer_external_id from an unverified JWT payload.
+
+    :param oauth_token: The OAuth access token.
+    :return: The customer external ID, or None if absent or unreadable.
+    :internal
+    """
+    try:
+        value = json.loads(base64url_decode(oauth_token.split(".")[1]))["ext"]["customer_external_id"]
+    except (IndexError, KeyError, TypeError, ValueError):
+        return None
+
+    return value if isinstance(value, string_types) and value else None

{cloudinary-1.46.3 → cloudinary-1.47.0}/cloudinary/docs/README.md

@@ -40,6 +40,7 @@ directory of the repository.
 - [Transform and deliver an image](transform-and-deliver-image.md)
 - [Transform and deliver a video](transform-and-deliver-video.md)
 - [Search and manage assets](search-and-manage-assets.md)
+- [Organize and share collections](organize-and-share-collections.md)
 - [Moderate an upload](moderate-upload.md)
 - [Use structured metadata](use-structured-metadata.md)
 - [Use with Django](use-with-django.md)

{cloudinary-1.46.3 → cloudinary-1.47.0}/cloudinary/docs/import-and-call.md

@@ -14,7 +14,8 @@ Import the submodules you use explicitly. `import cloudinary` on its own gives y
 `config()`, `CloudinaryImage`, `CloudinaryVideo`, `Search`, and `cloudinary.utils`,
 but **not** `cloudinary.uploader` or `cloudinary.api` — reaching for those raises
 `AttributeError: module 'cloudinary' has no attribute 'uploader'` until you import
-them.
+them. The same applies to `cloudinary.collections` — use
+`from cloudinary import collections`.
 
 Calls are synchronous and return plain dictionaries. Positional arguments come first,
 then keyword options that pass through to the API:

cloudinary-1.47.0/cloudinary/docs/organize-and-share-collections.md

@@ -0,0 +1,222 @@
+# Organize and share collections
+
+## When to use
+
+Grouping existing assets into a named set, and sharing that set through a public link.
+
+A collection references assets; it does not move, copy, or change them. Pick the right
+tool:
+
+- **Collection** (`cloudinary.collections`) — a curated set you name, list, and share as a
+  public page. An asset can be in many collections.
+- **Tag** (`uploader.add_tag`) — a label for filtering and bulk operations. No sharing.
+- **Folder** (`api.create_folder`) — where an asset lives. An asset has exactly one.
+- **Search** (`cloudinary.Search`) — a one-off query. Nothing is saved.
+
+There are two types of collection, fixed at creation:
+
+- **manual** (the default) — holds exactly the assets you add and remove.
+- **dynamic** — holds whatever matches a saved search expression, and updates itself as
+  assets start or stop matching. You cannot add or remove assets by hand.
+
+## Rules
+
+- `cloudinary.collections` must be imported explicitly. `import cloudinary` alone does not
+  load it.
+- Every response wraps its payload in `"data"`: `result["data"]["id"]`, not `result["id"]`.
+- Add and remove assets by `asset_id`. A `public_id` fails with `NotFound: Error 404 -
+  Unknown resource`.
+- Store the collection `id` and the public page `id`. Every other call takes them.
+- Never pass `None` as an ID. The SDK drops it from the URL and calls a different endpoint:
+  `collections.collection(None)` lists all collections instead of failing.
+
+## Complete flow
+
+```python
+import cloudinary
+import cloudinary.exceptions
+import cloudinary.uploader
+from cloudinary import collections  # must be imported explicitly
+
+# Configuration is read from CLOUDINARY_URL automatically.
+
+
+def main():
+    asset = cloudinary.uploader.upload("https://res.cloudinary.com/demo/image/upload/sample.jpg")
+
+    collection = collections.create_collection(
+        "Summer campaign",
+        description="Approved images for the launch",
+    )["data"]
+
+    collections.add_collection_assets(collection["id"], [asset["asset_id"]])
+
+    page = collections.create_collection_public_page(collection["id"], name="Launch preview")["data"]
+    print(page["url"])  # https://collection.cloudinary.com/<cloud_name>/<page_id>
+
+    return collection["id"], page["id"]
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except cloudinary.exceptions.Error as error:
+        print("Collections call failed: {0}".format(error))
+        raise SystemExit(1)
+```
+
+## Result fields to keep
+
+| Call | Returns | Keep |
+|---|---|---|
+| `create_collection`, `update_collection`, `add_collection_assets`, `remove_collection_assets` | `{"data": {collection}}` | `data.id` |
+| `collection` | `{"data": {collection}}`, plus `asset_count` and `cover_asset_url` | |
+| `collections`, `collection_assets` | `{"data": [...], "total_count": N, "next_cursor": "..."}` | `next_cursor` |
+| `create_collection_public_page`, `update_collection_public_page`, `collection_public_page` | `{"data": {page}}` | `data.id`, `data.url` |
+| `collection_public_pages` | `{"data": [...]}` | |
+| `delete_collection`, `delete_collection_public_page` | `{"message": "..."}` | |
+
+A collection has `id`, `name`, `description`, `type`, `configuration`, `created_at`, and
+`updated_at`. An asset in `collection_assets` has `asset_id`, `public_id`, `display_name`,
+`resource_type`, `type`, `format`, `bytes`, `width`, `height`, `secure_url`, and
+`created_at`.
+
+## Managing assets in a manual collection
+
+```python
+collections.add_collection_assets(collection_id, ["asset_id_1", "asset_id_2"])
+collections.add_collection_assets(collection_id, "asset_id_3")      # a single ID works too
+collections.remove_collection_assets(collection_id, ["asset_id_1"])
+```
+
+Adding an asset that is already in the collection succeeds and changes nothing. Removing an
+asset does not delete it.
+
+Changes can take a few seconds to show up in `collection_assets`. For read-after-write, poll
+until the asset appears instead of reading once.
+
+## Dynamic collections
+
+```python
+collection = collections.create_collection(
+    "Summer images",
+    type="dynamic",
+    configuration={"expression": "tags=summer AND resource_type:image"},
+)["data"]
+
+collections.update_collection(collection["id"], configuration={"expression": "tags=summer"})
+```
+
+The expression uses the same syntax as `cloudinary.Search`. A new dynamic collection takes a few seconds to populate.
+
+## Listing and paging
+
+```python
+cursor = None
+while True:
+    page = collections.collection_assets(collection_id, sort_by="created_at desc",
+                                         max_results=100, next_cursor=cursor)
+    for asset in page["data"]:
+        print(asset["asset_id"], asset["secure_url"])
+    cursor = page.get("next_cursor")
+    if not cursor:
+        break
+```
+
+`next_cursor` is absent on the last page; read it with `.get()`. Send the same `sort_by` on
+every page — a cursor is only valid for the sort it was issued with, and the server does not
+reject a mismatch.
+
+| Option | `collections` | `collection_assets` |
+|---|---|---|
+| `max_results` | 1-100, default 20 | 1-100, default 20 |
+| `sort_by` | `name`, `created_at`, `updated_at` + `asc`/`desc`; default `updated_at desc` | `created_at`, `uploaded_at`, `public_id`, `display_name`, `bytes` + `asc`/`desc`; default `created_at desc` |
+| `query` | matches a word in the name that starts with the text: `"sum"` matches "Summer campaign", `"umm"` does not | — |
+
+Combine sort keys with commas: `sort_by="name asc, created_at desc"`.
+
+## Sharing with public pages
+
+```python
+page = collections.create_collection_public_page(
+    collection_id,
+    name="Press kit",
+    expires_at="2026-12-31T00:00:00Z",
+    show_download_original_option=False,
+    download_transformations=[{"name": "thumbnail_400", "types": ["image"]}],
+    create_download_transformations=True,
+)["data"]
+
+collections.update_collection_public_page(collection_id, page["id"], name="Press kit (final)")
+collections.collection_public_pages(collection_id)
+collections.delete_collection_public_page(collection_id, page["id"])  # unpublish
+```
+
+Anyone with `page["url"]` can open the page until it expires or is unpublished. Unpublishing
+does not change the collection or its assets.
+
+- `download_transformations` must name existing named transformations, or the call fails with
+  `BadRequest: Error 400 - Unknown named transformation '<name>'`. Create one with
+  `cloudinary.api.create_transformation("thumbnail_400", "c_thumb,w_400")`.
+- The first time a named transformation is offered for download, pass
+  `create_download_transformations=True`. Without it the call fails with
+  `BadRequest: Error 400 - Named transformation '<name>' is not available for download yet`.
+- `types` (`["image"]`, `["video"]`, or omitted for both) is fixed the first time a name is
+  offered for download, on any public page. Later requests must omit it or send the same
+  list.
+- `show_download_original_option` defaults to `True`.
+- Restricting a page to specific viewers is update-only:
+  `update_collection_public_page(..., protection_mode="email_otp", allowed_emails=[...],
+  allowed_domains=[...])`. It needs the secured-sharing feature on your plan, or it fails
+  with `NotAllowed: Error 403 - Feature is not allowed`.
+
+## Updating and deleting
+
+```python
+collections.update_collection(collection_id, name="Summer campaign (final)")
+collections.delete_collection(collection_id)
+```
+
+Updates change only the fields you pass: `name`, `description`, and, for dynamic collections,
+`configuration`. The type cannot change; `type` is ignored on update. Deleting a collection
+does not delete its assets.
+
+## Authentication and plans
+
+The methods work with an API key and secret, or with an OAuth token
+(`cloudinary.config(oauth_token=...)`, scope `asset_management`).
+
+Collections are a premium Assets Enterprise feature. On the Assets Free plan you can have at
+most 3 collections, with up to 50 assets each. Dynamic collections and protected public pages
+must be enabled for your product environment.
+
+## Troubleshooting
+
+- `NotAllowed: Error 403 - Cannot have more than 3 classic collections` — the plan's
+  collection limit. Delete a collection or upgrade.
+- `NotAllowed: Error 403 - Feature is not allowed` — dynamic collections or `email_otp`
+  protection are not enabled for your product environment.
+- ``NotFound: Error 404 - We can`t find a collection with this id ...`` — wrong or deleted
+  collection ID.
+- `NotFound: Error 404 - Unknown resource` from add or remove — you passed a `public_id`, or
+  an `asset_id` that does not exist.
+- `NotAcceptable: Error 406 - unsupported operation for dynamic collection` — you tried to add
+  or remove assets in a dynamic collection. Change its expression instead.
+- `BadRequest: Error 400 - dynamic collections require a configuration with a non-empty
+  expression` — `type="dynamic"` without `configuration`.
+- `BadRequest: Error 400 - configuration is only allowed for dynamic collections` —
+  `configuration` on a manual collection.
+- `BadRequest: Error 400 - Unknown named transformation ...` or `... is not available for
+  download yet` — see [Sharing with public pages](#sharing-with-public-pages).
+- `BadRequest: Error 400 - invalid sort_by field ...` or `... max_results ...` — see the
+  options table above.
+- An asset you just added is missing from `collection_assets` — wait a few seconds and read
+  again.
+- A call returned every collection instead of one — the ID was `None`.
+
+## Related
+
+- Runnable example: `examples/organize-and-share-collections.py`
+- [Search and manage assets](search-and-manage-assets.md) — finding the `asset_id` values to
+  add, and the expression syntax for dynamic collections.
+- [Import and call the SDK](import-and-call.md)

{cloudinary-1.46.3 → cloudinary-1.47.0}/cloudinary/docs/platform-capabilities.md

@@ -99,6 +99,7 @@ URL building is local: no network call, no `api_secret`.
 | Read, update, restore, or delete an asset; manage folders and presets | `api` — the Assets Admin API | [Search and manage assets](search-and-manage-assets.md) |
 | Attach and query typed metadata fields | `api` + upload options | [Use structured metadata](use-structured-metadata.md) |
 | Find visually similar assets | `api.visual_search` — needs the feature enabled | [Visual Search](https://cloudinary.com/documentation/visual_search.md) |
+| Group assets into manual or dynamic collections and share them as public pages | `collections` — import explicitly, needs Collections on your plan | [Organize and share collections](organize-and-share-collections.md) |
 
 ## Analyze
 

{cloudinary-1.46.3 → cloudinary-1.47.0}/cloudinary/docs/troubleshoot-errors.md

@@ -10,9 +10,12 @@ Failures raise exceptions from `cloudinary.exceptions`, mapped from the HTTP sta
 | `AuthorizationRequired` | 401 | Missing or wrong credentials, bad signature |
 | `NotAllowed` | 403 | Valid credentials without permission for this operation |
 | `NotFound` | 404 | No such asset, folder, or preset |
+| `NotAcceptable` | 406 | The operation is not supported for this resource (for example, adding assets to a dynamic collection) |
 | `AlreadyExists` | 409 | The resource exists (duplicate `external_id`, folder) |
 | `RateLimited` | 420 / 429 | Hourly API limit reached, **or** an add-on you are not subscribed to |
+| `Locked` | 423 | The asset is still processing |
 | `GeneralError` | 500 / 503 | A server-side failure |
+| `Error` | any other status | |
 
 All of them subclass `cloudinary.exceptions.Error`, so one handler catches everything:
 
@@ -126,9 +129,7 @@ uploading a large video, or while an eager or add-on-driven transformation is st
 running. This is transient: retry with backoff rather than treating it as a failure. For
 long jobs, prefer `eager_async=True` with a `notification_url` over polling.
 
-Note that 423 is not in this SDK's status-to-exception map, so it surfaces as a plain
-`Exception` rather than a `cloudinary.exceptions.Error` subclass — a handler that catches
-only `cloudinary.exceptions.Error` will miss it.
+It raises `cloudinary.exceptions.Locked`, so you can retry on that class specifically.
 
 ### A transformation is missing from the generated URL
 

{cloudinary-1.46.3 → cloudinary-1.47.0}/cloudinary/exceptions.py

@@ -25,6 +25,14 @@ class BadRequest(Error):
     pass
 
 
+class NotAcceptable(Error):
+    pass
+
+
+class Locked(Error):
+    pass
+
+
 class GeneralError(Error):
     pass
 

{cloudinary-1.46.3 → cloudinary-1.47.0}/cloudinary/uploader.py

@@ -1,4 +1,5 @@
 # Copyright Cloudinary
+from __future__ import absolute_import
 
 import json
 import os

{cloudinary-1.46.3 → cloudinary-1.47.0}/cloudinary/utils.py

@@ -1,4 +1,6 @@
 # Copyright Cloudinary
+from __future__ import absolute_import
+
 import base64
 import copy
 import hashlib