contentstack-utils 1.4.0__tar.gz → 1.6.0__tar.gz

{contentstack_utils-1.4.0 → contentstack_utils-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contentstack_utils
-Version: 1.4.0
+Version: 1.6.0
 Summary: contentstack_utils is a Utility package for Contentstack headless CMS with an API-first approach.
 Home-page: https://github.com/contentstack/contentstack-utils-python
 Author: contentstack

{contentstack_utils-1.4.0 → contentstack_utils-1.6.0}/contentstack_utils/__init__.py

@@ -10,14 +10,18 @@ __author__, __status__, __version__, __endpoint__ and __email__
 
 from contentstack_utils.embedded.item_type import ItemType
 from contentstack_utils.embedded.styletype import StyleType
+from contentstack_utils.endpoint import Endpoint
 from contentstack_utils.helper.metadata import Metadata
 from contentstack_utils.helper.node_to_html import NodeToHtml
 from contentstack_utils.render.options import Options
 from contentstack_utils.utils import Utils
 from contentstack_utils.gql import GQL
 from contentstack_utils.automate import Automate
+from contentstack_utils.entry_editable import addEditableTags, addTags, getTag
+from contentstack_utils.region_refresh import refresh_regions
 
 __all__ = (
+"Endpoint",
 "Utils",
 "Options",
 "Metadata",
@@ -25,12 +29,16 @@ __all__ = (
 "Automate",
 "StyleType",
 "ItemType",
-"NodeToHtml"
+"NodeToHtml",
+"addEditableTags",
+"addTags",
+"getTag",
+"refresh_regions",
 )
 
 __title__ = 'contentstack_utils'
 __author__ = 'contentstack'
 __status__ = 'debug'
-__version__ = '1.4.0'
+__version__ = '1.6.0'
 __endpoint__ = 'cdn.contentstack.io'
 __contact__ = 'support@contentstack.com'

contentstack_utils-1.6.0/contentstack_utils/endpoint.py

@@ -0,0 +1,242 @@
+"""
+Endpoint resolution for Contentstack services across all regions.
+
+Reads a bundled regions.json (src/assets/regions.json) and resolves
+the correct base URL for any region + service combination. No runtime
+HTTP calls — the file is shipped with the package and updated via
+``python scripts/refresh_regions.py``.
+"""
+
+import json
+import os
+import re
+import urllib.request
+from typing import Dict, Optional, Union
+
+_REGIONS_URL = "https://artifacts.contentstack.com/regions.json"
+_ASSETS_DIR = os.path.join(os.path.dirname(__file__), "assets")
+_REGIONS_FILE = os.path.join(_ASSETS_DIR, "regions.json")
+
+
+class Endpoint:
+    """
+    Resolve Contentstack service URLs for any region.
+
+    All public methods are static — no instantiation required.
+
+    Example::
+
+        from contentstack_utils import Endpoint
+
+        # Full URL
+        url = Endpoint.get_contentstack_endpoint("na", "contentDelivery")
+        # → "https://cdn.contentstack.io"
+
+        # Host only (strip https://) — useful for SDK setHost() calls
+        host = Endpoint.get_contentstack_endpoint("eu", "contentDelivery", omit_https=True)
+        # → "eu-cdn.contentstack.com"
+
+        # All endpoints for a region
+        all_endpoints = Endpoint.get_contentstack_endpoint("azure-na")
+        # → {"contentDelivery": "...", "contentManagement": "...", ...}
+    """
+
+    # Module-level cache — loaded once per Python process, shared across all calls.
+    _regions_data: Optional[Dict] = None
+
+    @staticmethod
+    def get_contentstack_endpoint(
+        region: str = "us",
+        service: str = "",
+        omit_https: bool = False,
+    ) -> Union[str, Dict[str, str]]:
+        """
+        Resolve a Contentstack service endpoint URL for the given region.
+
+        :param region:
+            Region ID or any accepted alias (case-insensitive, ``-`` and ``_``
+            are interchangeable). Examples: ``'na'``, ``'us'``, ``'eu'``,
+            ``'AWS-NA'``, ``'azure_eu'``, ``'gcp-na'``.
+            Defaults to ``'us'`` (AWS North America).
+        :param service:
+            Optional service key. When provided, a single URL string is
+            returned. When omitted, a dict of **all** service URLs is returned.
+            Valid keys include: ``'contentDelivery'``, ``'contentManagement'``,
+            ``'auth'``, ``'graphqlDelivery'``, ``'preview'``, ``'images'``,
+            ``'assets'``, ``'automate'``, ``'launch'``, ``'developerHub'``,
+            ``'brandKit'``, ``'genAI'``, ``'personalizeManagement'``,
+            ``'personalizeEdge'``, ``'composableStudio'``, ``'assetManagement'``.
+        :param omit_https:
+            When ``True``, strips the ``https://`` (or ``http://``) scheme from
+            every returned URL. Useful when passing the host to an SDK that
+            constructs its own URLs (e.g. ``stack.set_host(host)``).
+        :returns:
+            - A ``str`` URL when *service* is specified.
+            - A ``dict[str, str]`` mapping service keys → URLs when *service*
+              is omitted.
+        :raises ValueError:
+            If *region* is an empty string.
+        :raises LookupError:
+            If *region* does not match any known region ID or alias, or if
+            *service* is not present in the resolved region's endpoint map.
+        :raises RuntimeError:
+            If the bundled ``regions.json`` cannot be read or is malformed.
+
+        Examples::
+
+            Endpoint.get_contentstack_endpoint("na", "contentDelivery")
+            # → "https://cdn.contentstack.io"
+
+            Endpoint.get_contentstack_endpoint("eu", "contentDelivery", omit_https=True)
+            # → "eu-cdn.contentstack.com"
+
+            Endpoint.get_contentstack_endpoint("azure-na")
+            # → {"contentDelivery": "https://...", ...}
+        """
+        if not region:
+            raise ValueError("Empty region provided. Please put valid region.")
+
+        data = Endpoint._load_regions()
+        normalized = region.strip().lower()
+
+        if not normalized:
+            raise ValueError("Empty region provided. Please put valid region.")
+        region_row = Endpoint._find_region_by_id_or_alias(data["regions"], normalized)
+
+        if region_row is None:
+            raise LookupError(f"Invalid region: {region}")
+
+        if service:
+            endpoints = region_row["endpoints"]
+            if service not in endpoints:
+                raise LookupError(
+                    f'Service "{service}" not found for region "{region_row["id"]}"'
+                )
+            url = endpoints[service]
+            return Endpoint._strip_https(url) if omit_https else url
+
+        endpoints = dict(region_row["endpoints"])
+        return Endpoint._strip_https_from_map(endpoints) if omit_https else endpoints
+
+
+    getContentstackEndpoint = get_contentstack_endpoint
+
+    @staticmethod
+    def reset_cache() -> None:
+        """
+        Clear the in-memory region cache.
+
+        Intended for testing only — forces the next call to re-read
+        ``regions.json`` from disk.
+        """
+        Endpoint._regions_data = None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _load_regions() -> Dict:
+        """
+        Load and cache regions data.
+
+        Resolution order:
+          1. In-memory cache (zero I/O after the first call in a process)
+          2. Bundled ``contentstack_utils/assets/regions.json`` on disk
+          3. Live download from ``artifacts.contentstack.com`` (fallback when
+             the file is absent — e.g. an editable install without assets)
+        """
+        if Endpoint._regions_data is not None:
+            return Endpoint._regions_data
+
+        if not os.path.exists(_REGIONS_FILE):
+            Endpoint._download_and_save(_REGIONS_FILE)
+
+        if not os.path.exists(_REGIONS_FILE):
+            raise RuntimeError(
+                "contentstack_utils: regions.json not found and could not be downloaded. "
+                "Run 'python scripts/refresh_regions.py' and ensure network access."
+            )
+
+        try:
+            with open(_REGIONS_FILE, "r", encoding="utf-8") as fh:
+                raw = fh.read()
+        except OSError as exc:
+            raise RuntimeError(
+                f"contentstack_utils: Could not read regions.json: {exc}"
+            ) from exc
+
+        try:
+            decoded = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise RuntimeError(
+                "contentstack_utils: regions.json is corrupt. "
+                "Run 'python scripts/refresh_regions.py' to re-download it."
+            ) from exc
+
+        if not isinstance(decoded, dict) or "regions" not in decoded:
+            raise RuntimeError(
+                "contentstack_utils: regions.json is corrupt. "
+                "Run 'python scripts/refresh_regions.py' to re-download it."
+            )
+
+        Endpoint._regions_data = decoded
+        return Endpoint._regions_data
+
+    @staticmethod
+    def _download_and_save(dest: str) -> None:
+        """
+        Fetch regions.json from the Contentstack CDN and write it to *dest*.
+
+        Silent on failure — the caller decides whether a missing file is fatal.
+        """
+        os.makedirs(os.path.dirname(dest), exist_ok=True)
+        try:
+            with urllib.request.urlopen(_REGIONS_URL, timeout=30) as resp:
+                data = resp.read().decode("utf-8")
+        except Exception:
+            return
+
+        try:
+            decoded = json.loads(data)
+        except json.JSONDecodeError:
+            return
+
+        if isinstance(decoded, dict) and "regions" in decoded:
+            with open(dest, "w", encoding="utf-8") as fh:
+                fh.write(data)
+
+    @staticmethod
+    def _find_region_by_id_or_alias(
+        regions: list, normalized_input: str
+    ) -> Optional[Dict]:
+        """
+        Find a region by its ``id`` field first, then by any alias.
+
+        Both passes are case-insensitive (caller must pass a lowercased string).
+        Two-pass approach mirrors the PHP implementation: ID match wins over alias
+        match, which avoids surprising behaviour when a future alias happens to
+        collide with another region's canonical ID.
+        """
+        # Pass 1 — exact id match
+        for row in regions:
+            if row["id"] == normalized_input:
+                return row
+
+        # Pass 2 — alias match
+        for row in regions:
+            for alias in row.get("alias", []):
+                if alias.lower() == normalized_input:
+                    return row
+
+        return None
+
+    @staticmethod
+    def _strip_https(url: str) -> str:
+        """Strip ``https://`` or ``http://`` from the start of a URL."""
+        return re.sub(r"^https?://", "", url)
+
+    @staticmethod
+    def _strip_https_from_map(endpoints: Dict[str, str]) -> Dict[str, str]:
+        """Return a new dict with the scheme stripped from every URL value."""
+        return {key: Endpoint._strip_https(url) for key, url in endpoints.items()}

contentstack_utils-1.6.0/contentstack_utils/entry_editable.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Union, cast
+
+
+AppliedVariants = Optional[Dict[str, Any]]
+TagValue = Union[str, Dict[str, str]]
+
+
+def _get_parent_variantised_path(applied_variants: Dict[str, Any], meta_key: str) -> str:
+    """
+    Port of JS getParentVariantisedPath().
+    Finds the longest variantised field path that is a prefix of meta_key.
+    """
+    try:
+        if not meta_key:
+            return ""
+        variantised_field_paths = sorted(applied_variants.keys(), key=len, reverse=True)
+        child_fragments = meta_key.split(".")
+        if not child_fragments or not variantised_field_paths:
+            return ""
+        for path in variantised_field_paths:
+            parent_fragments = str(path).split(".")
+            if len(parent_fragments) > len(child_fragments):
+                continue
+            if all(child_fragments[i] == parent_fragments[i] for i in range(len(parent_fragments))):
+                return str(path)
+        return ""
+    except Exception:
+        return ""
+
+
+def _apply_variant_to_data_value(data_value: str, applied_variants: AppliedVariants, meta_key: str, should_apply_variant: bool) -> str:
+    """
+    Port of JS applyVariantToDataValue().
+
+    If the current field (or its parent field path) is variantised, prefixes with
+    'v2:' and appends `_{variant}` to the entry uid segment of the dot-path.
+    """
+    if not should_apply_variant or not applied_variants or not meta_key or not isinstance(applied_variants, dict):
+        return data_value
+
+    variant: Optional[str] = None
+    if meta_key in applied_variants:
+        variant = str(applied_variants[meta_key])
+    else:
+        parent_path = _get_parent_variantised_path(applied_variants, meta_key)
+        if parent_path:
+            variant = str(applied_variants.get(parent_path))
+
+    if not variant:
+        return data_value
+
+    parts = ("v2:" + data_value).split(".")
+    if len(parts) >= 2:
+        parts[1] = parts[1] + "_" + variant
+    return ".".join(parts)
+
+
+def _tags_value(data_value: str, tags_as_object: bool, applied_variants: AppliedVariants, meta_key: str, should_apply_variant: bool) -> TagValue:
+    resolved = _apply_variant_to_data_value(data_value, applied_variants, meta_key, should_apply_variant)
+    if tags_as_object:
+        return {"data-cslp": resolved}
+    return f"data-cslp={resolved}"
+
+
+def _parent_tags_value(data_value: str, tags_as_object: bool) -> TagValue:
+    if tags_as_object:
+        return {"data-cslp-parent-field": data_value}
+    return f"data-cslp-parent-field={data_value}"
+
+
+def getTag(  # pylint: disable=invalid-name
+    content: Any,
+    prefix: str,
+    tags_as_object: bool,
+    locale: str,
+    applied_variants: AppliedVariants,
+    should_apply_variant: bool,
+    meta_key: str = "",
+) -> Dict[str, Any]:
+    """
+    Port of JS getTag() from `src/entry-editable.ts`.
+
+    Returns a dict mapping field keys to CSLP tag values, and mutates nested objects/refs
+    by attaching their own `$` tag maps.
+    """
+    if content is None or not isinstance(content, dict):
+        return {}
+
+    tags: Dict[str, Any] = {}
+    for key, value in content.items():
+        if key == "$":
+            continue
+
+        meta_uid = ""
+        if isinstance(value, dict):
+            meta = value.get("_metadata")
+            if isinstance(meta, dict) and meta.get("uid"):
+                meta_uid = str(meta.get("uid"))
+
+        meta_key_prefix = (meta_key + ".") if meta_key else ""
+        updated_meta_key = f"{meta_key_prefix}{key}" if should_apply_variant else ""
+        if meta_uid and updated_meta_key:
+            updated_meta_key = updated_meta_key + "." + meta_uid
+
+        if isinstance(value, list):
+            for index, obj in enumerate(value):
+                if obj is None:
+                    continue
+
+                child_key = f"{key}__{index}"
+                parent_key = f"{key}__parent"
+
+                obj_meta_uid = ""
+                if isinstance(obj, dict):
+                    meta = obj.get("_metadata")
+                    if isinstance(meta, dict) and meta.get("uid"):
+                        obj_meta_uid = str(meta.get("uid"))
+
+                array_meta_key = f"{meta_key_prefix}{key}" if should_apply_variant else ""
+                if obj_meta_uid and array_meta_key:
+                    array_meta_key = array_meta_key + "." + obj_meta_uid
+
+                tags[child_key] = _tags_value(
+                    f"{prefix}.{key}.{index}",
+                    tags_as_object,
+                    applied_variants,
+                    array_meta_key,
+                    should_apply_variant,
+                )
+                tags[parent_key] = _parent_tags_value(f"{prefix}.{key}", tags_as_object)
+
+                # Reference entries in array
+                if isinstance(obj, dict) and obj.get("_content_type_uid") is not None and obj.get("uid") is not None:
+                    new_applied_variants = obj.get("_applied_variants")
+                    if new_applied_variants is None and isinstance(obj.get("system"), dict):
+                        new_applied_variants = cast(dict, obj["system"]).get("applied_variants")
+                    new_should_apply_variant = bool(new_applied_variants)
+
+                    obj_locale = obj.get("locale") or locale
+                    obj["$"] = getTag(
+                        obj,
+                        f"{obj.get('_content_type_uid')}.{obj.get('uid')}.{obj_locale}",
+                        tags_as_object,
+                        locale,
+                        cast(AppliedVariants, new_applied_variants),
+                        new_should_apply_variant,
+                        meta_key="",
+                    )
+                    continue
+
+                if isinstance(obj, dict):
+                    obj["$"] = getTag(
+                        obj,
+                        f"{prefix}.{key}.{index}",
+                        tags_as_object,
+                        locale,
+                        applied_variants,
+                        should_apply_variant,
+                        meta_key=array_meta_key,
+                    )
+
+            tags[key] = _tags_value(
+                f"{prefix}.{key}",
+                tags_as_object,
+                applied_variants,
+                updated_meta_key,
+                should_apply_variant,
+            )
+            continue
+
+        if isinstance(value, dict):
+            value["$"] = getTag(
+                value,
+                f"{prefix}.{key}",
+                tags_as_object,
+                locale,
+                applied_variants,
+                should_apply_variant,
+                meta_key=updated_meta_key,
+            )
+            tags[key] = _tags_value(
+                f"{prefix}.{key}",
+                tags_as_object,
+                applied_variants,
+                updated_meta_key,
+                should_apply_variant,
+            )
+            continue
+
+        tags[key] = _tags_value(
+            f"{prefix}.{key}",
+            tags_as_object,
+            applied_variants,
+            updated_meta_key,
+            should_apply_variant,
+        )
+
+    return tags
+
+
+def addTags(  # pylint: disable=invalid-name
+    entry: Optional[dict],
+    contentTypeUid: str,
+    tagsAsObject: bool,
+    locale: str = "en-us",
+    options: Optional[dict] = None,
+) -> None:
+    """
+    Port of JS addTags() from `src/entry-editable.ts`.
+    Mutates `entry` by attaching a `$` dict of CSLP tags.
+    """
+    if not entry:
+        return
+
+    use_lower_case_locale = True
+    if isinstance(options, dict) and "useLowerCaseLocale" in options:
+        use_lower_case_locale = bool(options.get("useLowerCaseLocale"))
+
+    content_type_uid = (contentTypeUid or "").lower()
+    resolved_locale = (locale or "en-us")
+    if use_lower_case_locale:
+        resolved_locale = resolved_locale.lower()
+
+    applied_variants = entry.get("_applied_variants")
+    if applied_variants is None and isinstance(entry.get("system"), dict):
+        applied_variants = cast(dict, entry["system"]).get("applied_variants")
+    should_apply_variant = bool(applied_variants)
+
+    entry["$"] = getTag(
+        entry,
+        f"{content_type_uid}.{entry.get('uid')}.{resolved_locale}",
+        tagsAsObject,
+        resolved_locale,
+        cast(AppliedVariants, applied_variants),
+        should_apply_variant,
+        meta_key="",
+    )
+
+
+# JS parity export name
+addEditableTags = addTags  # pylint: disable=invalid-name
+
+# Pythonic aliases
+add_tags = addTags
+get_tags = getTag
+

contentstack_utils-1.6.0/contentstack_utils/region_refresh.py

@@ -0,0 +1,82 @@
+"""
+Utility to pull the latest regions.json from the Contentstack CDN and
+overwrite the bundled copy at contentstack_utils/assets/regions.json.
+
+Exposed as a package-level function so tooling and CI pipelines can call it
+programmatically instead of invoking the script directly:
+
+    from contentstack_utils import refresh_regions
+    refresh_regions()
+"""
+
+import json
+import os
+import sys
+import urllib.request
+
+_REGIONS_URL = "https://artifacts.contentstack.com/regions.json"
+_ASSET_PATH = os.path.join(os.path.dirname(__file__), "assets", "regions.json")
+
+
+def refresh_regions(
+    url: str = _REGIONS_URL,
+    dest: str = _ASSET_PATH,
+    *,
+    timeout: int = 30,
+    silent: bool = False,
+) -> dict:
+    """
+    Download the latest regions manifest from the Contentstack CDN and write
+    it to the bundled assets file so all consumers get the update.
+
+    @param url    - URL to fetch regions.json from (defaults to Contentstack CDN)
+    @param dest   - Destination file path (defaults to contentstack_utils/assets/regions.json)
+    @param timeout - HTTP request timeout in seconds
+    @param silent - Suppress progress output when True
+    @returns The parsed regions dict on success
+    @raises RuntimeError on download failure, invalid JSON, or unexpected schema
+    """
+    dest = os.path.normpath(dest)
+
+    if not silent:
+        print(f"Fetching {url} ...")
+
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            data = resp.read().decode("utf-8")
+    except Exception as exc:
+        raise RuntimeError(f"Could not download regions.json: {exc}") from exc
+
+    try:
+        decoded = json.loads(data)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"Downloaded content is not valid JSON: {exc}") from exc
+
+    if not isinstance(decoded, dict) or "regions" not in decoded:
+        raise RuntimeError("Downloaded JSON does not contain a 'regions' key.")
+
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    with open(dest, "w", encoding="utf-8") as fh:
+        json.dump(decoded, fh, indent=2, ensure_ascii=False)
+        fh.write("\n")
+
+    region_count = len(decoded["regions"])
+    if not silent:
+        print(f"OK: Wrote {region_count} regions to {dest}")
+
+    return decoded
+
+
+def _cli_main() -> int:
+    """Entry point kept for backward compatibility with the scripts/ invocation."""
+    try:
+        refresh_regions()
+        print("Next steps:")
+        return 0
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(_cli_main())

{contentstack_utils-1.4.0 → contentstack_utils-1.6.0}/contentstack_utils/utils.py

@@ -1,17 +1,70 @@
 # pylint: disable=missing-function-docstring
 
 import json
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Optional, Union
 
 from lxml import etree
 
 from contentstack_utils.automate import Automate
+from contentstack_utils.endpoint import Endpoint
+from contentstack_utils.entry_editable import addEditableTags as _addEditableTags
+from contentstack_utils.entry_editable import addTags as _addTags
+from contentstack_utils.entry_editable import getTag as _getTag
 from contentstack_utils.helper.converter import convert_style
 from contentstack_utils.helper.metadata import Metadata
 from contentstack_utils.render.options import Options
 
 
 class Utils(Automate):
+    # JS parity helpers (moved to `contentstack_utils/entry_editable.py`)
+    @staticmethod
+    def addTags(  # pylint: disable=invalid-name
+        entry: dict,
+        contentTypeUid: str,
+        tagsAsObject: Optional[bool] = None,
+        locale: str = "en-us",
+        options: Optional[dict] = None,
+        **kwargs,
+    ) -> None:
+        # Support pythonic kwarg name too (backward compatibility with earlier port).
+        if tagsAsObject is None and "tags_as_object" in kwargs:
+            tagsAsObject = bool(kwargs["tags_as_object"])
+        if tagsAsObject is None:
+            tagsAsObject = False
+        return _addTags(entry, contentTypeUid, tagsAsObject, locale, options)
+
+    @staticmethod
+    def addEditableTags(  # pylint: disable=invalid-name
+        entry: dict,
+        contentTypeUid: str,
+        tagsAsObject: Optional[bool] = None,
+        locale: str = "en-us",
+        options: Optional[dict] = None,
+        **kwargs,
+    ) -> None:
+        if tagsAsObject is None and "tags_as_object" in kwargs:
+            tagsAsObject = bool(kwargs["tags_as_object"])
+        if tagsAsObject is None:
+            tagsAsObject = False
+        return _addEditableTags(entry, contentTypeUid, tagsAsObject, locale, options)
+
+    @staticmethod
+    def getTag(  # pylint: disable=invalid-name
+        content: Any,
+        prefix: str,
+        tagsAsObject: bool,
+        locale: str,
+        appliedVariants: Optional[dict],
+        shouldApplyVariant: bool,
+        metaKey: str = "",
+    ) -> Dict[str, Any]:
+        # Keep JS argument names for parity.
+        return _getTag(content, prefix, tagsAsObject, locale, appliedVariants, shouldApplyVariant, metaKey)
+
+    # Pythonic aliases
+    add_tags = addTags
+    get_tags = getTag
+    get_tag = getTag
 
     @staticmethod
     def _variants_map_from_entry(entry: dict) -> dict:
@@ -167,6 +220,34 @@ class Utils(Automate):
             metadata = Metadata(element.text, typeof, uid, content_type, style, outer_html, attributes)
             return metadata
 
+    # ------------------------------------------------------------------
+    # Endpoint resolution — thin proxy to Endpoint class
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def get_contentstack_endpoint(
+        region: str = "us",
+        service: str = "",
+        omit_https: bool = False,
+    ):
+        """
+        Resolve a Contentstack service URL for the given region.
+
+        Delegates entirely to :class:`~contentstack_utils.endpoint.Endpoint`.
+        Both ``Utils.get_contentstack_endpoint(...)`` and
+        ``Endpoint.get_contentstack_endpoint(...)`` produce identical results —
+        choose whichever import path suits your codebase.
+
+        :param region: Region ID or alias (e.g. ``'na'``, ``'eu'``, ``'azure-na'``).
+        :param service: Optional service key (e.g. ``'contentDelivery'``).
+        :param omit_https: Strip ``https://`` from the returned URL(s).
+        :returns: URL string when *service* is given, dict of all URLs otherwise.
+        """
+        return Endpoint.get_contentstack_endpoint(region, service, omit_https)
+
+    # camelCase alias for cross-SDK parity
+    getContentstackEndpoint = get_contentstack_endpoint
+
     ####################################################
     #                   SUPERCHARGED                   #
     ####################################################

{contentstack_utils-1.4.0 → contentstack_utils-1.6.0}/contentstack_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contentstack_utils
-Version: 1.4.0
+Version: 1.6.0
 Summary: contentstack_utils is a Utility package for Contentstack headless CMS with an API-first approach.
 Home-page: https://github.com/contentstack/contentstack-utils-python
 Author: contentstack

{contentstack_utils-1.4.0 → contentstack_utils-1.6.0}/contentstack_utils.egg-info/SOURCES.txt

@@ -3,7 +3,10 @@ README.md
 setup.py
 contentstack_utils/__init__.py
 contentstack_utils/automate.py
+contentstack_utils/endpoint.py
+contentstack_utils/entry_editable.py
 contentstack_utils/gql.py
+contentstack_utils/region_refresh.py
 contentstack_utils/utils.py
 contentstack_utils.egg-info/PKG-INFO
 contentstack_utils.egg-info/SOURCES.txt
@@ -21,6 +24,8 @@ contentstack_utils/render/options.py
 tests/__init__.py
 tests/convert_style.py
 tests/test_default_opt_others.py
+tests/test_editable_tags.py
+tests/test_endpoint.py
 tests/test_gql_to_html_func.py
 tests/test_helper_node_to_html.py
 tests/test_item_types.py

{contentstack_utils-1.4.0 → contentstack_utils-1.6.0}/setup.py

@@ -1,7 +1,23 @@
 import os
+import sys
 
 from setuptools import setup, find_packages
-from distutils.core import setup
+from setuptools.command.build_py import build_py
+
+
+class BuildPyWithRegions(build_py):
+    """Fetch latest regions.json from Contentstack CDN before packaging."""
+
+    def run(self):
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        try:
+            from contentstack_utils.region_refresh import refresh_regions
+            refresh_regions()
+        except Exception as exc:
+            # Never block a build over a network failure — warn and continue.
+            print(f"WARNING: Could not refresh regions.json: {exc}", file=sys.stderr)
+        super().run()
+
 
 with open(os.path.join(os.path.dirname(__file__), 'README.md')) as readme:
     long_description = readme.read()
@@ -9,19 +25,23 @@ with open(os.path.join(os.path.dirname(__file__), 'README.md')) as readme:
 setup(
     name='contentstack_utils',
     packages=find_packages(),
+    package_data={
+        "contentstack_utils": ["assets/regions.json"],
+    },
     description="contentstack_utils is a Utility package for Contentstack headless CMS with an API-first approach.",
     author='contentstack',
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/contentstack/contentstack-utils-python",
     license='MIT',
-    version='1.4.0',
+    version='1.6.0',
     install_requires=[
-        
+
     ],
     setup_requires=['pytest-runner'],
     tests_require=['pytest==4.4.1'],
     test_suite='tests',
+    cmdclass={"build_py": BuildPyWithRegions},
     classifiers=[
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",

{contentstack_utils-1.4.0 → contentstack_utils-1.6.0}/tests/convert_style.py

@@ -10,7 +10,7 @@ class TestConvertStyle(unittest.TestCase):
 
     def test_converter_style_block(self):
         _returns = converter.convert_style('block')
-        self.assertEquals(StyleType.BLOCK, _returns)
+        self.assertEqual(StyleType.BLOCK, _returns)
 
     def test_converter_style_inline(self):
         _returns = converter.convert_style('inline')

contentstack_utils-1.6.0/tests/test_editable_tags.py

@@ -0,0 +1,56 @@
+import unittest
+
+from contentstack_utils.utils import Utils
+
+
+class TestEditableTags(unittest.TestCase):
+    def test_add_tags_mutates_entry_with_dollar_map(self):
+        entry = {"uid": "e1", "title": "Hello", "count": 1}
+        Utils.addTags(entry, "Blog_Post", tags_as_object=True, locale="EN-us")
+        self.assertIn("$", entry)
+        self.assertEqual(entry["$"]["title"], {"data-cslp": "blog_post.e1.en-us.title"})
+        self.assertEqual(entry["$"]["count"], {"data-cslp": "blog_post.e1.en-us.count"})
+
+    def test_add_tags_string_mode(self):
+        entry = {"uid": "e1", "title": "Hello"}
+        Utils.addTags(entry, "blog_post", tags_as_object=False, locale="en-us")
+        self.assertEqual(entry["$"]["title"], "data-cslp=blog_post.e1.en-us.title")
+
+    def test_array_tags_add_index_and_parent_keys(self):
+        entry = {"uid": "e1", "array": ["hello", "world"]}
+        Utils.addTags(entry, "blog", tags_as_object=True, locale="en-us")
+        self.assertEqual(entry["$"]["array"], {"data-cslp": "blog.e1.en-us.array"})
+        self.assertEqual(entry["$"]["array__0"], {"data-cslp": "blog.e1.en-us.array.0"})
+        self.assertEqual(entry["$"]["array__1"], {"data-cslp": "blog.e1.en-us.array.1"})
+        self.assertEqual(entry["$"]["array__parent"], {"data-cslp-parent-field": "blog.e1.en-us.array"})
+
+    def test_reference_entry_inside_array_gets_own_dollar(self):
+        entry = {
+            "uid": "e1",
+            "refs": [
+                {
+                    "uid": "r1",
+                    "_content_type_uid": "ref_ct",
+                    "title": "Ref Title",
+                }
+            ],
+        }
+        Utils.addTags(entry, "blog", tags_as_object=True, locale="en-us")
+        ref = entry["refs"][0]
+        self.assertIn("$", ref)
+        self.assertEqual(ref["$"]["title"], {"data-cslp": "ref_ct.r1.en-us.title"})
+
+    def test_variantised_field_applies_v2_prefix_and_uid_suffix(self):
+        entry = {
+            "uid": "e1",
+            "_applied_variants": {"title": "v123"},
+            "title": {"value": "Hello"},
+        }
+        Utils.addTags(entry, "blog", tags_as_object=True, locale="en-us")
+        # title is an object; ensure we tag the object itself (like JS) and apply variant.
+        self.assertEqual(entry["$"]["title"], {"data-cslp": "v2:blog.e1_v123.en-us.title"})
+
+
+if __name__ == "__main__":
+    unittest.main()
+

contentstack_utils-1.6.0/tests/test_endpoint.py

@@ -0,0 +1,264 @@
+"""
+Tests for contentstack_utils.endpoint.Endpoint and the Utils proxy.
+"""
+
+import pytest
+
+from contentstack_utils.endpoint import Endpoint
+from contentstack_utils.utils import Utils
+
+
+@pytest.fixture(autouse=True)
+def reset_cache():
+    """Isolate each test — forces a fresh regions.json read."""
+    Endpoint.reset_cache()
+    yield
+    Endpoint.reset_cache()
+
+
+# ---------------------------------------------------------------------------
+# Default region (us / na)
+# ---------------------------------------------------------------------------
+
+class TestDefaultRegion:
+    def test_returns_all_endpoints_when_no_service(self):
+        endpoints = Endpoint.get_contentstack_endpoint()
+        assert isinstance(endpoints, dict)
+        assert "contentDelivery" in endpoints
+        assert "contentManagement" in endpoints
+
+    def test_content_delivery_url(self):
+        url = Endpoint.get_contentstack_endpoint("us", "contentDelivery")
+        assert url == "https://cdn.contentstack.io"
+
+    def test_content_management_url(self):
+        url = Endpoint.get_contentstack_endpoint("us", "contentManagement")
+        assert url == "https://api.contentstack.io"
+
+
+# ---------------------------------------------------------------------------
+# NA region alias resolution
+# ---------------------------------------------------------------------------
+
+NA_ALIASES = ["na", "us", "aws-na", "aws_na", "NA", "US", "AWS-NA", "AWS_NA"]
+
+@pytest.mark.parametrize("alias", NA_ALIASES)
+def test_na_aliases_resolve_to_same_cdn(alias):
+    url = Endpoint.get_contentstack_endpoint(alias, "contentDelivery")
+    assert url == "https://cdn.contentstack.io"
+
+
+# ---------------------------------------------------------------------------
+# All 7 regions — contentDelivery spot-checks
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("region,expected", [
+    ("na",       "https://cdn.contentstack.io"),
+    ("eu",       "https://eu-cdn.contentstack.com"),
+    ("au",       "https://au-cdn.contentstack.com"),
+    ("azure-na", "https://azure-na-cdn.contentstack.com"),
+    ("azure-eu", "https://azure-eu-cdn.contentstack.com"),
+    ("gcp-na",   "https://gcp-na-cdn.contentstack.com"),
+    ("gcp-eu",   "https://gcp-eu-cdn.contentstack.com"),
+])
+def test_content_delivery_by_region(region, expected):
+    assert Endpoint.get_contentstack_endpoint(region, "contentDelivery") == expected
+
+
+# ---------------------------------------------------------------------------
+# All 7 regions — contentManagement spot-checks
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("region,expected", [
+    ("na",       "https://api.contentstack.io"),
+    ("eu",       "https://eu-api.contentstack.com"),
+    ("au",       "https://au-api.contentstack.com"),
+    ("azure-na", "https://azure-na-api.contentstack.com"),
+    ("azure-eu", "https://azure-eu-api.contentstack.com"),
+    ("gcp-na",   "https://gcp-na-api.contentstack.com"),
+    ("gcp-eu",   "https://gcp-eu-api.contentstack.com"),
+])
+def test_content_management_by_region(region, expected):
+    assert Endpoint.get_contentstack_endpoint(region, "contentManagement") == expected
+
+
+# ---------------------------------------------------------------------------
+# All expected service keys present
+# ---------------------------------------------------------------------------
+
+EXPECTED_SERVICE_KEYS = [
+    "application", "contentDelivery", "contentManagement", "auth",
+    "graphqlDelivery", "preview", "graphqlPreview", "images", "assets",
+    "automate", "launch", "developerHub", "brandKit", "genAI",
+    "personalizeManagement", "personalizeEdge", "composableStudio",
+]
+
+def test_all_service_keys_present_for_eu():
+    endpoints = Endpoint.get_contentstack_endpoint("eu")
+    for key in EXPECTED_SERVICE_KEYS:
+        assert key in endpoints, f"Missing service key: {key}"
+
+def test_na_has_asset_management_key():
+    # NA is the only region that currently includes assetManagement.
+    endpoints = Endpoint.get_contentstack_endpoint("na")
+    assert "assetManagement" in endpoints
+
+
+# ---------------------------------------------------------------------------
+# omit_https flag
+# ---------------------------------------------------------------------------
+
+class TestOmitHttps:
+    def test_strips_scheme_from_single_service(self):
+        host = Endpoint.get_contentstack_endpoint("eu", "contentDelivery", omit_https=True)
+        assert host == "eu-cdn.contentstack.com"
+
+    def test_strips_scheme_from_all_services(self):
+        endpoints = Endpoint.get_contentstack_endpoint("na", omit_https=True)
+        assert isinstance(endpoints, dict)
+        for key, url in endpoints.items():
+            assert "https://" not in url, f"Service {key} still has https://"
+            assert "http://" not in url, f"Service {key} still has http://"
+
+    def test_false_retains_scheme(self):
+        url = Endpoint.get_contentstack_endpoint("na", "contentManagement", omit_https=False)
+        assert url.startswith("https://")
+
+    def test_omit_https_positional_argument(self):
+        # Confirm the third positional arg is honoured (mirrors PHP signature).
+        host = Endpoint.get_contentstack_endpoint("gcp-na", "contentDelivery", True)
+        assert host == "gcp-na-cdn.contentstack.com"
+
+
+# ---------------------------------------------------------------------------
+# Case-insensitive and underscore alias matching
+# ---------------------------------------------------------------------------
+
+class TestAliasMatching:
+    def test_uppercase_alias(self):
+        url = Endpoint.get_contentstack_endpoint("AWS-NA", "contentDelivery")
+        assert url == "https://cdn.contentstack.io"
+
+    def test_underscore_azure_alias(self):
+        url = Endpoint.get_contentstack_endpoint("azure_na", "contentDelivery")
+        assert url == "https://azure-na-cdn.contentstack.com"
+
+    def test_underscore_gcp_alias(self):
+        url = Endpoint.get_contentstack_endpoint("gcp_eu", "contentManagement")
+        assert url == "https://gcp-eu-api.contentstack.com"
+
+    def test_mixed_case_eu(self):
+        url = Endpoint.get_contentstack_endpoint("EU", "contentDelivery")
+        assert url == "https://eu-cdn.contentstack.com"
+
+    def test_mixed_case_au(self):
+        url = Endpoint.get_contentstack_endpoint("AU", "contentDelivery")
+        assert url == "https://au-cdn.contentstack.com"
+
+
+# ---------------------------------------------------------------------------
+# Return-all-endpoints (no service argument)
+# ---------------------------------------------------------------------------
+
+class TestNoService:
+    def test_returns_dict(self):
+        result = Endpoint.get_contentstack_endpoint("au")
+        assert isinstance(result, dict)
+        assert len(result) > 1
+
+    def test_dict_contains_correct_urls(self):
+        endpoints = Endpoint.get_contentstack_endpoint("au")
+        assert endpoints["contentDelivery"] == "https://au-cdn.contentstack.com"
+        assert endpoints["contentManagement"] == "https://au-api.contentstack.com"
+
+    def test_default_call_returns_na(self):
+        endpoints = Endpoint.get_contentstack_endpoint()
+        assert endpoints["contentDelivery"] == "https://cdn.contentstack.io"
+
+
+# ---------------------------------------------------------------------------
+# Error cases
+# ---------------------------------------------------------------------------
+
+class TestErrorCases:
+    def test_empty_region_raises_value_error(self):
+        with pytest.raises(ValueError, match="Empty region provided"):
+            Endpoint.get_contentstack_endpoint("")
+
+    def test_unknown_region_raises_lookup_error(self):
+        with pytest.raises(LookupError, match="Invalid region: invalid-region"):
+            Endpoint.get_contentstack_endpoint("invalid-region")
+
+    def test_unknown_service_raises_lookup_error(self):
+        with pytest.raises(LookupError, match='Service "unknownService" not found'):
+            Endpoint.get_contentstack_endpoint("na", "unknownService")
+
+    def test_whitespace_region_raises_value_error(self):
+        with pytest.raises(ValueError, match="Empty region provided"):
+            Endpoint.get_contentstack_endpoint("   ")
+
+
+# ---------------------------------------------------------------------------
+# camelCase alias (cross-SDK parity)
+# ---------------------------------------------------------------------------
+
+class TestCamelCaseAlias:
+    def test_get_contentstack_endpoint_camel_case(self):
+        url = Endpoint.getContentstackEndpoint("na", "contentDelivery")
+        assert url == "https://cdn.contentstack.io"
+
+    def test_camel_case_and_snake_case_return_same(self):
+        snake = Endpoint.get_contentstack_endpoint("eu", "contentDelivery")
+        camel = Endpoint.getContentstackEndpoint("eu", "contentDelivery")
+        assert snake == camel
+
+
+# ---------------------------------------------------------------------------
+# Utils proxy
+# ---------------------------------------------------------------------------
+
+class TestUtilsProxy:
+    def test_proxy_returns_same_as_endpoint_class(self):
+        via_endpoint = Endpoint.get_contentstack_endpoint("eu", "contentDelivery")
+        via_utils = Utils.get_contentstack_endpoint("eu", "contentDelivery")
+        assert via_endpoint == via_utils
+
+    def test_proxy_default_region(self):
+        url = Utils.get_contentstack_endpoint("us", "contentManagement")
+        assert url == "https://api.contentstack.io"
+
+    def test_proxy_omit_https(self):
+        host = Utils.get_contentstack_endpoint("gcp-na", "contentDelivery", omit_https=True)
+        assert host == "gcp-na-cdn.contentstack.com"
+
+    def test_proxy_all_endpoints(self):
+        endpoints = Utils.get_contentstack_endpoint("azure-eu")
+        assert isinstance(endpoints, dict)
+        assert "contentDelivery" in endpoints
+
+    def test_proxy_camel_case_alias(self):
+        url = Utils.getContentstackEndpoint("na", "contentDelivery")
+        assert url == "https://cdn.contentstack.io"
+
+    def test_proxy_error_propagates(self):
+        with pytest.raises(LookupError):
+            Utils.get_contentstack_endpoint("not-a-region", "contentDelivery")
+
+
+# ---------------------------------------------------------------------------
+# Cache behaviour
+# ---------------------------------------------------------------------------
+
+class TestCache:
+    def test_second_call_uses_cache(self, reset_cache):
+        from unittest.mock import patch, MagicMock
+        Endpoint.get_contentstack_endpoint("na", "contentDelivery")
+        with patch("builtins.open", wraps=open) as spy:
+            Endpoint.get_contentstack_endpoint("eu", "contentDelivery")
+            spy.assert_not_called()
+
+    def test_reset_cache_clears_data(self):
+        Endpoint.get_contentstack_endpoint("na")  # primes cache
+        assert Endpoint._regions_data is not None
+        Endpoint.reset_cache()
+        assert Endpoint._regions_data is None