Skip to content

Commit 6469b57

Browse files
const-cloudinaryconst-cloudinary
committed
Add missing doc strings
1 parent 6a4f518 commit 6469b57

2 files changed

Lines changed: 221 additions & 5 deletions

File tree

‎cloudinary/api.py‎

Lines changed: 109 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,16 @@
2929

3030

3131
def ping(**options):
32+
"""
33+
Tests the reachability of the Cloudinary API.
34+
35+
:param options: Additional options.
36+
:type options: dict, optional
37+
:return: The result of the API call.
38+
:rtype: Response
39+
40+
See: https://cloudinary.com/documentation/admin_api#ping
41+
"""
3242
return call_api("get", ["ping"], {}, **options)
3343

3444

@@ -39,7 +49,7 @@ def usage(**options):
3949
requests, number of resources, and add-on usage. Note that numbers are updated periodically.
4050
4151
See: `Get account usage details
42-
<https://cloudinary.com/documentation/admin_api#get_account_usage_details>`_
52+
<https://cloudinary.com/documentation/admin_api#get_product_environment_usage_details>`_
4353
4454
:param options: Additional options
4555
:type options: dict, optional
@@ -59,7 +69,9 @@ def config(**options):
5969
"""
6070
Get account config details.
6171
62-
:param options: Additional options.
72+
Fetches the account's configuration details with optional settings.
73+
74+
:param options: The optional parameters for the API request.
6375
:type options: dict, optional
6476
:return: Detailed config information.
6577
:rtype: Response
@@ -69,10 +81,26 @@ def config(**options):
6981

7082

7183
def resource_types(**options):
84+
"""
85+
Retrieves the types of resources (assets) available.
86+
87+
:param options: Additional options.
88+
:type options: dict, optional
89+
:return: The result of the API call.
90+
:rtype: Response
91+
"""
7292
return call_api("get", ["resources"], {}, **options)
7393

7494

7595
def resources(**options):
96+
"""
97+
Retrieves resources (assets) based on the provided options.
98+
99+
:param options: Additional options to filter the resources.
100+
:type options: dict, optional
101+
:return: The result of the API call.
102+
:rtype: Response
103+
"""
76104
resource_type = options.pop("resource_type", "image")
77105
upload_type = options.pop("type", None)
78106
uri = ["resources", resource_type]
@@ -84,20 +112,62 @@ def resources(**options):
84112

85113

86114
def resources_by_tag(tag, **options):
115+
"""
116+
Lists resources (assets) with the specified tag.
117+
118+
This method does not return matching deleted assets, even if they have been backed up.
119+
120+
:param tag: The tag value.
121+
:type tag: str
122+
:param options: The optional parameters.
123+
:type options: dict, optional
124+
:return: The result of the API call.
125+
:rtype: Response
126+
127+
See: https://cloudinary.com/documentation/admin_api#get_resources_by_tag
128+
"""
87129
resource_type = options.pop("resource_type", "image")
88130
uri = ["resources", resource_type, "tags", tag]
89131
params = __list_resources_params(**options)
90132
return call_api("get", uri, params, **options)
91133

92134

93135
def resources_by_moderation(kind, status, **options):
136+
"""
137+
Lists resources (assets) assets currently in the specified moderation queue and status.
138+
139+
:param kind: Type of image moderation queue to list.
140+
Valid values: "manual", "webpurify", "aws_rek", or "metascan".
141+
:type kind: str
142+
:param status: Only assets with this moderation status will be returned.
143+
Valid values: "pending", "approved", "rejected".
144+
:type status: str
145+
:param options: The optional parameters.
146+
:type options: dict, optional
147+
:return: The result of the API call.
148+
:rtype: Response
149+
150+
See: https://cloudinary.com/documentation/admin_api#get_resources_in_moderation_queues
151+
"""
94152
resource_type = options.pop("resource_type", "image")
95153
uri = ["resources", resource_type, "moderations", kind, status]
96154
params = __list_resources_params(**options)
97155
return call_api("get", uri, params, **options)
98156

99157

100158
def resources_by_ids(public_ids, **options):
159+
"""
160+
Lists resources (assets) with the specified public IDs.
161+
162+
:param public_ids: The requested public_ids (up to 100).
163+
:type public_ids: list[str]
164+
:param options: The optional parameters.
165+
:type options: dict, optional
166+
:return: The result of the API call.
167+
:rtype: Response
168+
169+
See: https://cloudinary.com/documentation/admin_api#get_resources
170+
"""
101171
resource_type = options.pop("resource_type", "image")
102172
upload_type = options.pop("type", "upload")
103173
uri = ["resources", resource_type, upload_type]
@@ -127,7 +197,7 @@ def resources_by_asset_ids(asset_ids, **options):
127197
This method does not return deleted assets even if they have been backed up.
128198
129199
See: `Get resources by context API reference
130-
<https://cloudinary.com/documentation/admin_api#get_resources>`_
200+
<https://cloudinary.com/documentation/admin_api#get_resources_by_asset_ids>`_
131201
132202
:param asset_ids: The requested asset IDs.
133203
:type asset_ids: list[str]
@@ -219,6 +289,19 @@ def visual_search(image_url=None, image_asset_id=None, text=None, image_file=Non
219289

220290

221291
def resource(public_id, **options):
292+
"""
293+
Returns the details of the specified asset and all its derived assets.
294+
295+
Note that if you only need details about the original asset, you can also use the `uploader.upload`
296+
or `uploader.explicit` methods, which return the same information and are not rate limited.
297+
298+
:param public_id: The public ID of the resource.
299+
:type public_id: str
300+
:param options: Additional options.
301+
:type options: dict, optional
302+
:return: The result of the API call.
303+
:rtype: Response
304+
"""
222305
resource_type = options.pop("resource_type", "image")
223306
upload_type = options.pop("type", "upload")
224307
uri = ["resources", resource_type, upload_type, public_id]
@@ -257,6 +340,16 @@ def _prepare_asset_details_params(**options):
257340

258341

259342
def update(public_id, **options):
343+
"""
344+
Updates the details of a specified resource.
345+
346+
:param public_id: The public ID of the resource to update.
347+
:type public_id: str
348+
:param options: Additional options for the update operation.
349+
:type options: dict, optional
350+
:return: The result of the API call.
351+
:rtype: Response
352+
"""
260353
resource_type = options.pop("resource_type", "image")
261354
upload_type = options.pop("type", "upload")
262355
uri = ["resources", resource_type, upload_type, public_id]
@@ -299,6 +392,7 @@ def delete_resources(public_ids, **options):
299392
params = __delete_resource_params(options, public_ids=public_ids)
300393
return call_api("delete", uri, params, **options)
301394

395+
302396
def delete_resources_by_asset_ids(asset_ids, **options):
303397
"""
304398
Deletes resources (assets) by asset IDs.
@@ -472,6 +566,16 @@ def delete_related_assets_by_asset_ids(asset_id, assets_to_unrelate, **options):
472566

473567

474568
def tags(**options):
569+
"""
570+
Lists all the tags currently used for a specified asset type.
571+
572+
:param options: The optional parameters.
573+
:type options: dict, optional
574+
:return: The result of the API call.
575+
:rtype: Response
576+
577+
See: https://cloudinary.com/documentation/admin_api#get_tags
578+
"""
475579
resource_type = options.pop("resource_type", "image")
476580
uri = ["tags", resource_type]
477581
return call_api("get", uri, only(options, "next_cursor", "max_results", "prefix"), **options)
@@ -624,6 +728,7 @@ def restore(public_ids, **options):
624728
params = dict(public_ids=public_ids, **only(options, "versions"))
625729
return call_json_api("post", uri, params, **options)
626730

731+
627732
def restore_by_asset_ids(asset_ids, **options):
628733
"""
629734
Restores resources (assets) by their asset IDs.
@@ -639,6 +744,7 @@ def restore_by_asset_ids(asset_ids, **options):
639744
params = dict(asset_ids=asset_ids, **only(options, "versions"))
640745
return call_json_api("post", uri, params, **options)
641746

747+
642748
def upload_mappings(**options):
643749
uri = ["upload_mappings"]
644750
return call_api("get", uri, only(options, "next_cursor", "max_results"), **options)

0 commit comments

Comments
 (0)