asset.py

r"""Assets refer to all the media files (images, videos, PDFs, audio files,
and so on) uploaded in your Contentstack repository for future use.

These files can be attached and used in multiple entries.
"""

import logging
from urllib import parse
from contentstack.error_messages import ErrorMessages

class Asset:
    r"""`Asset` refer to all the media files (images, videos, PDFs, audio files, and so on)."""

    def __init__(self, http_instance, uid=None, logger=None):
        self.http_instance = http_instance
        self.asset_params = {}
        self.__uid = uid
        if self.__uid is None or self.__uid.strip() == 0:
            raise KeyError(ErrorMessages.INVALID_UID)
        self.uid = uid
        self.base_url = f'{self.http_instance.endpoint}/assets/{self.__uid}'
        if 'environment' in self.http_instance.headers:
            self.asset_params['environment'] = self.http_instance.headers['environment']
        self.logger = logger or logging.getLogger(__name__)

    def environment(self, environment):
        r"""Provide the name of the environment if you wish to retrieve the assets published
        in a particular environment.
        :param environment {str} - name of the environment
        :return: `Asset`, so we can chain the call
        -------------------------------
        [Example]:
            >>> import contentstack
            >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
            >>> asset = stack.asset(uid='asset_uid')
            >>> asset = asset.environment('production')
        -------------------------------
        """
        if environment is not None or environment is str:
            self.http_instance.headers['environment'] = environment
        return self

    def remove_environment(self):
        r"""Removes environment from the request params
        :return: `Asset`, so we can chain the call
        -------------------------------
        [Example]:
            >>> import contentstack
            >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
            >>> asset = stack.asset(uid='asset_uid')
            >>> asset = asset.remove_header()
            >>> asset.fetch()
        -------------------------------
        """
        if 'environment' in self.http_instance.headers:
            self.http_instance.headers.pop('environment')
        return self

    def params(self, key, value):
        r"""params is used to pass additional parameters to the asset query
        :param key: key of the query parameter
        :param value: value of the query parameter
        :return: `Asset`, so we can chain the call
        -----------------------------
        Example::
            >>> import contentstack
            >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
            >>> asset = stack.asset(uid='asset_uid')
            >>> asset = asset.params('key', 'value')
        -----------------------------
        """
        if None in (key, value) or not isinstance(key, str):
            raise KeyError(ErrorMessages.INVALID_PARAMS)
        self.asset_params[key] = value
        return self

    def relative_urls(self):
        """Include the relative URLs of the assets in the response.
        :return: `Asset`, so we can chain the call
        ----------------------------
        Example::
            >>> import contentstack
            >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
            >>> asset = stack.asset(uid='asset_uid')
            >>> asset = asset.relative_urls()
        ----------------------------
        """
        self.asset_params['relative_urls'] = 'true'
        return self

    def include_dimension(self):
        r"""Include the dimensions (height and width) of the image in the response.
        Supported image types: JPG, GIF, PNG, WebP, BMP, TIFF, SVG, and PSD.
        :return: `Asset`, so we can chain the call
        ----------------------------
        Example::
            >>> import contentstack
            >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
            >>> asset = stack.asset(uid='asset_uid')
            >>> asset = asset.include_dimension()
        ----------------------------
        """
        self.asset_params['include_dimension'] = "true"
        return self

    def include_fallback(self):
        r"""Retrieve the published content of the fallback locale if an
        entry is not localized in specified locale
        :return: `Asset`, so we can chain the call
        ----------------------------
        Example::
            >>> import contentstack
            >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
            >>> asset = stack.asset(uid='asset_uid')
            >>> result = asset.include_fallback().fetch()
        ----------------------------
        """
        self.asset_params['include_fallback'] = "true"
        return self

    def asset_fields(self, *field_names):
        r"""Include specific asset fields in the response.
        Supported values: user_defined_fields, embedded_metadata, ai_generated_metadata, visual_markups.
        Pass one or more field names. Can be called multiple times to add more fields.

        :param field_names: One or more asset field names (user_defined_fields, embedded_metadata, ai_generated_metadata, visual_markups)
        :return: `Asset`, so we can chain the call
        ----------------------------
        Example::
            >>> import contentstack
            >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
            >>> asset = stack.asset(uid='asset_uid')
            >>> result = asset.asset_fields('user_defined_fields', 'visual_markups').fetch()
        ----------------------------
        """
        if field_names:
            values = []
            for name in field_names:
                if isinstance(name, (list, tuple)):
                    values.extend(str(v) for v in name)
                else:
                    values.append(str(name))
            if values:
                existing = self.asset_params.get('asset_fields[]', [])
                if not isinstance(existing, list):
                    existing = [existing]
                self.asset_params['asset_fields[]'] = existing + values
        return self

    def fetch(self):
        r"""This call fetches the latest version of a specific asset of a particular stack.
        :return: json response of asset
        -----------------------------
        [Example]:
            >>> import contentstack
            >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
            >>> asset = stack.asset(uid='asset_uid')
            >>> result = asset.fetch()
        ------------------------------
        """
        url = f'{self.base_url}?{parse.urlencode(self.asset_params)}'
        return self.http_instance.get(url)