def update_metadata(metadata, public_ids, **options):
"""
Populates metadata fields with the given values. Existing values will be overwritten.
Any metadata-value pairs given are merged with any existing metadata-value pairs
(an empty value for an existing metadata field clears the value)
:param metadata: A list of custom metadata fields (by external_id) and the values to assign to each
of them.
:param public_ids: An array of Public IDs of assets uploaded to Cloudinary.
:param options: Options such as
*resource_type* (the type of file. Default: image. Valid values: image, raw, or video) and
*type* (The storage type. Default: upload. Valid values: upload, private, or authenticated.)
:return: A list of public IDs that were updated
:rtype: mixed
"""
params = {
"timestamp": utils.now(),
"metadata": utils.encode_context(metadata),
"public_ids": utils.build_array(public_ids),
"type": options.get("type")
}
return call_api("metadata", params, **options)
def build_eager(transformations):
eager = []
for tr in utils.build_array(transformations):
format = tr.get("format")
single_eager = "/".join([x for x in [utils.generate_transformation_string(**tr)[0], format] if x])
eager.append(single_eager)
return "|".join(eager)
def build_upload_params(**options):
params = {
"timestamp":
now(),
"transformation":
utils.generate_transformation_string(**options)[0],
"public_id":
options.get("public_id"),
"callback":
options.get("callback"),
"format":
options.get("format"),
"type":
options.get("type"),
"backup":
options.get("backup"),
"faces":
options.get("faces"),
"exif":
options.get("exif"),
"colors":
options.get("colors"),
"headers":
build_custom_headers(options.get("headers")),
"eager":
build_eager(options.get("eager")),
"tags":
options.get("tags") and ",".join(utils.build_array(options["tags"]))
}
return params
def upload_large_part(file, **options):
""" Upload large raw files. Note that public_id should include an extension for best results. """
params = {
"timestamp":
utils.now(),
"type":
options.get("type"),
"backup":
options.get("backup"),
"final":
options.get("final"),
"part_number":
options.get("part_number"),
"upload_id":
options.get("upload_id"),
"tags":
options.get("tags") and ",".join(utils.build_array(options["tags"])),
"public_id":
options.get("public_id")
}
return call_api("upload_large",
params,
resource_type="raw",
file=file,
**options)
def build_eager(transformations):
eager = []
for tr in utils.build_array(transformations):
format = tr.get("format")
single_eager = "/".join([x for x in [utils.generate_transformation_string(**tr)[0], format] if x])
eager.append(single_eager)
return "|".join(eager)
def explicit(public_id, **options):
params = {
"timestamp":
utils.now(),
"type":
options.get("type"),
"public_id":
public_id,
"callback":
options.get("callback"),
"headers":
utils.build_custom_headers(options.get("headers")),
"eager":
utils.build_eager(options.get("eager")),
"eager_notification_url":
options.get("eager_notification_url"),
"eager_async":
options.get("eager_async"),
"tags":
options.get("tags") and ",".join(utils.build_array(options["tags"])),
"face_coordinates":
utils.encode_double_array(options.get("face_coordinates")),
"custom_coordinates":
utils.encode_double_array(options.get("custom_coordinates")),
"invalidate":
options.get("invalidate"),
"context":
utils.encode_dict(options.get("context")),
"responsive_breakpoints":
utils.generate_responsive_breakpoints_string(
options.get("responsive_breakpoints"))
}
return call_api("explicit", params, **options)
def call_tags_api(tag, command, public_ids = [], **options):
params = {
"timestamp": now(),
"tag": tag,
"public_ids": utils.build_array(public_ids),
"command": command
}
return call_api("tags", params, **options)
def call_tags_api(tag, command, public_ids=None, **options):
params = {
"timestamp": utils.now(),
"tag": tag,
"public_ids": utils.build_array(public_ids),
"command": command,
"type": options.get("type")
}
return call_api("tags", params, **options)
def call_context_api(context, command, public_ids=None, **options):
params = {
"timestamp": utils.now(),
"context": utils.encode_context(context),
"public_ids": utils.build_array(public_ids),
"command": command,
"type": options.get("type")
}
return call_api("context", params, **options)
def call_tags_api(tag, command, public_ids=None, **options):
params = {
"timestamp": utils.now(),
"tag": tag,
"public_ids": utils.build_array(public_ids),
"command": command,
"type": options.get("type")
}
return call_api("tags", params, **options)
def call_context_api(context, command, public_ids=None, **options):
params = {
"timestamp": utils.now(),
"context": utils.encode_context(context),
"public_ids": utils.build_array(public_ids),
"command": command,
"type": options.get("type")
}
return call_api("context", params, **options)
def explicit(public_id, **options):
params = {
"timestamp": now(),
"type": options.get("type"),
"public_id": public_id,
"callback": options.get("callback"),
"headers": build_custom_headers(options.get("headers")),
"eager": build_eager(options.get("eager")),
"tags": options.get("tags") and ",".join(utils.build_array(options["tags"]))}
return call_api("explicit", params, **options)
def update(public_id, **options):
resource_type = options.pop("resource_type", "image")
type = options.pop("type", "upload")
uri = ["resources", resource_type, type, public_id]
upload_options = only(options, "moderation_status", "raw_convert", "ocr", "categorization", "detection", "similarity_search")
if "tags" in options: upload_options["tags"] = ",".join(utils.build_array(options["tags"]))
if "face_coordinates" in options: upload_options["face_coordinates"] = utils.encode_double_array(options.get("face_coordinates"))
if "context" in options: upload_options["context"] = utils.encode_dict(options.get("context"))
if "auto_tagging" in options: upload_options["auto_tagging"] = float(options.get("auto_tagging"))
return call_api("post", uri, upload_options, **options)
def explicit(public_id, **options):
params = {
"timestamp": now(),
"type": options.get("type"),
"public_id": public_id,
"callback": options.get("callback"),
"headers": build_custom_headers(options.get("headers")),
"eager": build_eager(options.get("eager")),
"tags": options.get("tags") and ",".join(utils.build_array(options["tags"]))}
return call_api("explicit", params, **options)
def build_upload_params(**options):
params = {"timestamp": now(),
"transformation" : utils.generate_transformation_string(**options)[0],
"public_id": options.get("public_id"),
"callback": options.get("callback"),
"format": options.get("format"),
"type": options.get("type"),
"backup": options.get("backup"),
"tags": options.get("tags") and ",".join(utils.build_array(options["tags"]))}
if "eager" in options:
params["eager"] = "|".join([utils.generate_transformation_string(**tr)[0] for tr in utils.build_array(options["eager"]) if tr])
return params
def build_upload_params(**options):
params = {"timestamp": now(),
"transformation" : utils.generate_transformation_string(**options)[0],
"public_id": options.get("public_id"),
"callback": options.get("callback"),
"format": options.get("format"),
"type": options.get("type"),
"backup": options.get("backup"),
"headers": build_custom_headers(options.get("headers")),
"eager": build_eager(options.get("eager")),
"tags": options.get("tags") and ",".join(utils.build_array(options["tags"]))}
return params
def upload_large_part(file, **options):
""" Upload large raw files. Note that public_id should include an extension for best results. """
params = {
"timestamp": utils.now(),
"type": options.get("type"),
"backup": options.get("backup"),
"final": options.get("final"),
"part_number": options.get("part_number"),
"upload_id": options.get("upload_id"),
"tags": options.get("tags") and ",".join(utils.build_array(options["tags"])),
"public_id": options.get("public_id")
}
return call_api("upload_large", params, resource_type="raw", file=file, **options)
def explicit(public_id, **options):
params = {
"timestamp": utils.now(),
"type": options.get("type"),
"public_id": public_id,
"callback": options.get("callback"),
"headers": utils.build_custom_headers(options.get("headers")),
"eager": utils.build_eager(options.get("eager")),
"eager_notification_url": options.get("eager_notification_url"),
"eager_async": options.get("eager_async"),
"tags": options.get("tags") and ",".join(utils.build_array(options["tags"])),
"face_coordinates": utils.encode_double_array(options.get("face_coordinates")),
"custom_coordinates": utils.encode_double_array(options.get("custom_coordinates"))}
return call_api("explicit", params, **options)
def build_upload_params(**options):
params = {"timestamp": utils.now(),
"transformation": utils.generate_transformation_string(**options)[0],
"public_id": options.get("public_id"),
"callback": options.get("callback"),
"format": options.get("format"),
"type": options.get("type"),
"backup": options.get("backup"),
"faces": options.get("faces"),
"image_metadata": options.get("image_metadata"),
"exif": options.get("exif"),
"colors": options.get("colors"),
"headers": build_custom_headers(options.get("headers")),
"eager": build_eager(options.get("eager")),
"use_filename": options.get("use_filename"),
"unique_filename": options.get("unique_filename"),
"discard_original_filename": options.get("discard_original_filename"),
"invalidate": options.get("invalidate"),
"notification_url": options.get("notification_url"),
"eager_notification_url": options.get("eager_notification_url"),
"eager_async": options.get("eager_async"),
"proxy": options.get("proxy"),
"folder": options.get("folder"),
"overwrite": options.get("overwrite"),
"tags": options.get("tags") and ",".join(utils.build_array(options["tags"])),
"allowed_formats": options.get("allowed_formats") and ",".join(utils.build_array(options["allowed_formats"])),
"face_coordinates": utils.encode_double_array(options.get("face_coordinates")),
"context": utils.encode_dict(options.get("context")),
"moderation": options.get("moderation"),
"raw_convert": options.get("raw_convert"),
"ocr": options.get("ocr"),
"categorization": options.get("categorization"),
"detection": options.get("detection"),
"similarity_search": options.get("similarity_search"),
"auto_tagging": options.get("auto_tagging") and float(options.get("auto_tagging"))}
params = dict( [ (k, __safe_value(v)) for (k,v) in params.items()] )
return params
def video(self, **options):
public_id = options.get('public_id', self.public_id)
source = re.sub("\.({0})$".format("|".join(self.default_source_types())), '', public_id)
source_types = options.pop('source_types', [])
source_transformation = options.pop('source_transformation', {})
fallback = options.pop('fallback_content', '')
options['resource_type'] = options.pop('resource_type', self.resource_type or self.default_resource_type or 'video')
if len(source_types) == 0: source_types = self.default_source_types()
video_options = options.copy()
if 'poster' in video_options:
poster_options = video_options['poster']
if isinstance(poster_options, dict):
if 'public_id' in poster_options:
video_options['poster'] = utils.cloudinary_url(poster_options['public_id'], **poster_options)[0]
else:
video_options['poster'] = self.video_thumbnail(public_id=source, **poster_options)
else:
video_options['poster'] = self.video_thumbnail(public_id=source, **options)
if not video_options['poster']: del video_options['poster']
html = '<video ';
nested_source_types = isinstance(source_types, list) and len(source_types) > 1
if not nested_source_types:
source = source + '.' + utils.build_array(source_types)[0];
video_url = utils.cloudinary_url(source, **video_options)
video_options = video_url[1]
if not nested_source_types:
video_options['src'] = video_url[0]
if 'html_width' in video_options: video_options['width'] = video_options.pop('html_width')
if 'html_height' in video_options: video_options['height'] = video_options.pop('html_height')
html = html + utils.html_attrs(video_options) + '>'
if nested_source_types:
for source_type in source_types:
transformation = options.copy()
transformation.update(source_transformation.get(source_type, {}))
src = utils.cloudinary_url(source, format = source_type, **transformation)[0]
video_type = "ogg" if source_type == 'ogv' else source_type
mime_type = "video/" + video_type
html = html + '<source ' + utils.html_attrs({'src': src, 'type': mime_type}) + '>'
html = html + fallback
html = html + '</video>'
return html
def video(self, **options):
public_id = options.get('public_id', self.public_id)
source = re.sub("\.{0}$".format("|".join(self.default_source_types())), '', public_id)
source_types = options.pop('source_types', [])
source_transformation = options.pop('source_transformation', {})
fallback = options.pop('fallback_content', '')
options['resource_type'] = options.pop('resource_type', self.resource_type or self.default_resource_type or 'video')
if len(source_types) == 0: source_types = self.default_source_types()
video_options = options.copy()
if 'poster' in video_options:
poster_options = video_options['poster']
if isinstance(poster_options, dict):
if 'public_id' in poster_options:
video_options['poster'] = utils.cloudinary_url(poster_options['public_id'], **poster_options)[0]
else:
video_options['poster'] = self.video_thumbnail(public_id=source, **poster_options)
else:
video_options['poster'] = self.video_thumbnail(public_id=source, **options)
if not video_options['poster']: del video_options['poster']
html = '<video ';
nested_source_types = isinstance(source_types, list) and len(source_types) > 1
if not nested_source_types:
source = source + '.' + utils.build_array(source_types)[0];
video_url = utils.cloudinary_url(source, **video_options)
video_options = video_url[1]
if not nested_source_types:
video_options['src'] = video_url[0]
if 'html_width' in video_options: video_options['width'] = video_options.pop('html_width')
if 'html_height' in video_options: video_options['height'] = video_options.pop('html_height')
html = html + utils.html_attrs(video_options) + '>'
if nested_source_types:
for source_type in source_types:
transformation = options.copy()
transformation.update(source_transformation.get(source_type, {}))
src = utils.cloudinary_url(source, format = source_type, **transformation)[0]
video_type = "ogg" if source_type == 'ogv' else source_type
mime_type = "video/" + video_type
html = html + '<source ' + utils.html_attrs({'src': src, 'type': mime_type}) + '>'
html = html + fallback
html = html + '</video>'
return html
def explicit(public_id, **options):
params = {
"timestamp": utils.now(),
"type": options.get("type"),
"public_id": public_id,
"callback": options.get("callback"),
"headers": utils.build_custom_headers(options.get("headers")),
"eager": utils.build_eager(options.get("eager")),
"eager_notification_url": options.get("eager_notification_url"),
"eager_async": options.get("eager_async"),
"tags": options.get("tags") and ",".join(utils.build_array(options["tags"])),
"face_coordinates": utils.encode_double_array(options.get("face_coordinates")),
"custom_coordinates": utils.encode_double_array(options.get("custom_coordinates")),
"invalidate": options.get("invalidate"),
"context": utils.encode_dict(options.get("context")),
"responsive_breakpoints": utils.generate_responsive_breakpoints_string(options.get("responsive_breakpoints")),
}
return call_api("explicit", params, **options)
def build_upload_params(**options):
params = {"timestamp": now(),
"transformation": utils.generate_transformation_string(**options)[0],
"public_id": options.get("public_id"),
"callback": options.get("callback"),
"format": options.get("format"),
"type": options.get("type"),
"backup": options.get("backup"),
"faces": options.get("faces"),
"image_metadata": options.get("image_metadata"),
"exif": options.get("exif"),
"colors": options.get("colors"),
"headers": build_custom_headers(options.get("headers")),
"eager": build_eager(options.get("eager")),
"use_filename": options.get("use_filename"),
"notification_url": options.get("notification_url"),
"eager_notification_url": options.get("eager_notification_url"),
"eager_async": options.get("eager_async"),
"tags": options.get("tags") and ",".join(utils.build_array(options["tags"]))}
return params
def create_slideshow(**options):
"""
Creates auto-generated video slideshows.
:param options: The optional parameters. See the upload API documentation.
:return: a dictionary with details about created slideshow
"""
options["resource_type"] = options.get("resource_type", "video")
params = {param_name: options.get(param_name) for param_name in _SLIDESHOW_PARAMS}
serialized_params = {
"timestamp": utils.now(),
"transformation": build_eager(options.get("transformation")),
"manifest_transformation": build_eager(options.get("manifest_transformation")),
"manifest_json": options.get("manifest_json") and utils.json_encode(options.get("manifest_json")),
"tags": options.get("tags") and utils.encode_list(utils.build_array(options["tags"])),
}
params.update(serialized_params)
return call_api("create_slideshow", params, **options)
def build_upload_params(**options):
params = {
"timestamp":
utils.now(),
"transformation":
utils.generate_transformation_string(**options)[0],
"public_id":
options.get("public_id"),
"callback":
options.get("callback"),
"format":
options.get("format"),
"type":
options.get("type"),
"backup":
options.get("backup"),
"faces":
options.get("faces"),
"image_metadata":
options.get("image_metadata"),
"exif":
options.get("exif"),
"colors":
options.get("colors"),
"headers":
build_custom_headers(options.get("headers")),
"eager":
build_eager(options.get("eager")),
"use_filename":
options.get("use_filename"),
"unique_filename":
options.get("unique_filename"),
"discard_original_filename":
options.get("discard_original_filename"),
"invalidate":
options.get("invalidate"),
"notification_url":
options.get("notification_url"),
"eager_notification_url":
options.get("eager_notification_url"),
"eager_async":
options.get("eager_async"),
"proxy":
options.get("proxy"),
"folder":
options.get("folder"),
"overwrite":
options.get("overwrite"),
"tags":
options.get("tags") and ",".join(utils.build_array(options["tags"])),
"allowed_formats":
options.get("allowed_formats")
and ",".join(utils.build_array(options["allowed_formats"])),
"face_coordinates":
utils.encode_double_array(options.get("face_coordinates")),
"context":
utils.encode_dict(options.get("context")),
"moderation":
options.get("moderation"),
"raw_convert":
options.get("raw_convert"),
"ocr":
options.get("ocr"),
"categorization":
options.get("categorization"),
"detection":
options.get("detection"),
"similarity_search":
options.get("similarity_search"),
"auto_tagging":
options.get("auto_tagging") and float(options.get("auto_tagging"))
}
params = dict([(k, __safe_value(v)) for (k, v) in params.items()])
return params
def video(self, **options):
"""
Creates an HTML video tag for the provided +source+
Examples:
CloudinaryResource("mymovie.mp4").video()
CloudinaryResource("mymovie.mp4").video(source_types = 'webm')
CloudinaryResource("mymovie.ogv").video(poster = "myspecialplaceholder.jpg")
CloudinaryResource("mymovie.webm").video(source_types = ['webm', 'mp4'], poster = {'effect': 'sepia'})
:param options:
* <tt>source_types</tt> - Specify which source type the tag should include.
defaults to webm, mp4 and ogv.
* <tt>source_transformation</tt> - specific transformations to use
for a specific source type.
* <tt>poster</tt> - override default thumbnail:
* url: provide an ad hoc url
* options: with specific poster transformations and/or Cloudinary +:public_id+
:return: Video tag
"""
public_id = options.get('public_id', self.public_id)
source = re.sub(r"\.({0})$".format("|".join(self.default_source_types())), '', public_id)
source_types = options.pop('source_types', [])
source_transformation = options.pop('source_transformation', {})
fallback = options.pop('fallback_content', '')
options['resource_type'] = options.pop('resource_type', self.resource_type or 'video')
if not source_types:
source_types = self.default_source_types()
video_options = options.copy()
if 'poster' in video_options:
poster_options = video_options['poster']
if isinstance(poster_options, dict):
if 'public_id' in poster_options:
video_options['poster'] = utils.cloudinary_url(poster_options['public_id'], **poster_options)[0]
else:
video_options['poster'] = self.video_thumbnail(
public_id=source, **poster_options)
else:
video_options['poster'] = self.video_thumbnail(public_id=source, **options)
if not video_options['poster']:
del video_options['poster']
nested_source_types = isinstance(source_types, list) and len(source_types) > 1
if not nested_source_types:
source = source + '.' + utils.build_array(source_types)[0]
video_url = utils.cloudinary_url(source, **video_options)
video_options = video_url[1]
if not nested_source_types:
video_options['src'] = video_url[0]
if 'html_width' in video_options:
video_options['width'] = video_options.pop('html_width')
if 'html_height' in video_options:
video_options['height'] = video_options.pop('html_height')
sources = ""
if nested_source_types:
for source_type in source_types:
transformation = options.copy()
transformation.update(source_transformation.get(source_type, {}))
src = utils.cloudinary_url(source, format=source_type, **transformation)[0]
video_type = "ogg" if source_type == 'ogv' else source_type
mime_type = "video/" + video_type
sources += "<source {attributes}>".format(attributes=utils.html_attrs({'src': src, 'type': mime_type}))
html = "<video {attributes}>{sources}{fallback}</video>".format(
attributes=utils.html_attrs(video_options), sources=sources, fallback=fallback)
return html
def video(self, **options):
"""
Creates an HTML video tag for the provided +source+
Examples:
CloudinaryResource("mymovie.mp4").video()
CloudinaryResource("mymovie.mp4").video(source_types = 'webm')
CloudinaryResource("mymovie.ogv").video(poster = "myspecialplaceholder.jpg")
CloudinaryResource("mymovie.webm").video(source_types = ['webm', 'mp4'], poster = {'effect': 'sepia'})
:param options:
* <tt>source_types</tt> - Specify which source type the tag should include.
defaults to webm, mp4 and ogv.
* <tt>sources</tt> - Similar to source_types, but may contain codecs list.
source_types and sources are mutually exclusive, only one of
them can be used. If both are not provided, default source types
are used.
* <tt>source_transformation</tt> - specific transformations to use
for a specific source type.
* <tt>poster</tt> - override default thumbnail:
* url: provide an ad hoc url
* options: with specific poster transformations and/or Cloudinary +:public_id+
:return: Video tag
"""
public_id = options.get('public_id', self.public_id)
source = re.sub(
r"\.({0})$".format("|".join(self.default_source_types())), '',
public_id)
custom_attributes = options.pop("attributes", dict())
fallback = options.pop('fallback_content', '')
# Save source types for a single video source handling (it can be a single type)
source_types = options.get('source_types', "")
poster_options = options.copy()
if "poster" not in custom_attributes:
options["poster"] = self._generate_video_poster_attr(
source, poster_options)
if "resource_type" not in options:
options["resource_type"] = self.resource_type or "video"
# populate video source tags
source_tags = self._populate_video_source_tags(source, options)
if not source_tags:
source = source + '.' + utils.build_array(source_types)[0]
video_url, video_options = utils.cloudinary_url(source, **options)
if not source_tags:
custom_attributes['src'] = video_url
attributes = self._collect_video_tag_attributes(video_options)
attributes.update(custom_attributes)
sources_str = ''.join(str(x) for x in source_tags)
html = "<video {attributes}>{sources}{fallback}</video>".format(
attributes=utils.html_attrs(attributes),
sources=sources_str,
fallback=fallback)
return html