contentstack-management 1.9.0__tar.gz → 1.10.0__tar.gz

{contentstack_management-1.9.0 → contentstack_management-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contentstack-management
-Version: 1.9.0
+Version: 1.10.0
 Summary: Contentstack API Client Library for Python
 Home-page: https://github.com/contentstack/contentstack-management-python
 Author: dev-ex

{contentstack_management-1.9.0 → contentstack_management-1.10.0}/contentstack_management/__init__.py

@@ -18,6 +18,7 @@ from .environments.environment import Environment
 from .entries.entry import Entry
 from .entry_variants.entry_variants import EntryVariants
 from .contentstack import Client, Region
+from .endpoint import Endpoint
 from ._api_client import _APIClient
 from .common import Parameter
 from ._errors import ArgumentException
@@ -36,11 +37,13 @@ from .variant_group.variant_group import VariantGroup
 from .variants.variants import Variants
 from .oauth.oauth_handler import OAuthHandler
 from .oauth.oauth_interceptor import OAuthInterceptor
+from .region_refresh import refresh_regions
 
 
 __all__ = (
 "Client",
 "Region",
+"Endpoint",
 "_APIClient",
 "Parameter",
 "ArgumentException",
@@ -75,14 +78,31 @@ __all__ = (
 "VariantGroup",
 "Variants",
 "OAuthHandler",
-"OAuthInterceptor"
+"OAuthInterceptor",
+"refresh_regions",
 )
 
+def get_contentstack_endpoint(region='us', service='', omit_https=False):
+    """
+    Resolve a Contentstack service endpoint URL for a given region.
+
+    Proxy to :class:`Endpoint.get_contentstack_endpoint` for convenience —
+    mirrors ``Contentstack::getContentstackEndpoint()`` in the PHP SDK.
+
+    :param region: Region ID or alias ('us', 'eu', 'azure-na', 'gcp-eu', ...).
+    :param service: Service key ('contentDelivery', 'contentManagement', ...).
+                    When empty, returns a dict of all endpoints for the region.
+    :param omit_https: When True, strips 'https://' from the returned URL(s).
+    :returns: str when service is provided, dict[str,str] otherwise.
+    """
+    return Endpoint.get_contentstack_endpoint(region, service, omit_https)
+
+
 __title__ = 'contentstack-management-python'
 __author__ = 'dev-ex'
 __status__ = 'debug'
 __region__ = 'na'
-__version__ = '1.9.0'
+__version__ = '1.10.0'
 __host__ = 'api.contentstack.io'
 __protocol__ = 'https://'
 __api_version__ = 'v3'

{contentstack_management-1.9.0 → contentstack_management-1.10.0}/contentstack_management/contentstack.py

@@ -2,6 +2,7 @@ from enum import Enum
 import os
 import pyotp
 from ._api_client import _APIClient
+from .endpoint import Endpoint
 from contentstack_management.organizations import organization
 from contentstack_management.stack import stack
 from contentstack_management.user_session import user_session
@@ -37,16 +38,25 @@ class Client:
                  authtoken: str = None , management_token=None, headers: dict = None,
                  region: Region = Region.US.value, version='v3', timeout=2, max_retries: int = 18, early_access: list = None,
                  oauth_config: dict = None, **kwargs):
-        self.endpoint = 'https://api.contentstack.io/v3/'
-        
-        if region is not None and region is not Region.US.value:
-            if host is not None and host != 'api.contentstack.io':
+        _DEFAULT_HOST = 'api.contentstack.io'
+        self.endpoint = f'{scheme}{_DEFAULT_HOST}/{version}/'
+
+        if host is None or host == _DEFAULT_HOST:
+            # No custom host — resolve via Endpoint (regions.json-driven)
+            try:
+                base = Endpoint.get_contentstack_endpoint(
+                    region or 'us', 'contentManagement', omit_https=True)
+                self.endpoint = f'{scheme}{base}/{version}/'
+            except (ValueError, RuntimeError):
+                # Unknown/custom region string — fall back to legacy pattern
+                if region and region != Region.US.value:
+                    self.endpoint = f'{scheme}{region}-api.contentstack.com/{version}/'
+        else:
+            # Explicit custom host always wins; apply region prefix when non-US
+            if region and region != Region.US.value:
                 self.endpoint = f'{scheme}{region}-api.{host}/{version}/'
             else:
-                host = 'api.contentstack.com'
-                self.endpoint = f'{scheme}{region}-{host}/{version}/'
-        elif host is not None and host != 'api.contentstack.io':
-            self.endpoint = f'{scheme}{host}/{version}/'
+                self.endpoint = f'{scheme}{host}/{version}/'
         if headers is None:
             headers = {}
         if early_access is not None:

contentstack_management-1.10.0/contentstack_management/endpoint.py

@@ -0,0 +1,180 @@
+"""
+Endpoint — Contentstack region-to-URL resolver for the Management SDK.
+
+Resolves Contentstack service endpoint URLs for any supported region.
+Region data is loaded from contentstack_management/data/regions.json (bundled)
+and cached in-memory for the lifetime of the process. When the bundled file is
+absent the class attempts a live download from the Contentstack CDN so the
+SDK continues to work even when the file was not created during installation.
+"""
+
+import json
+import os
+import re
+
+REGIONS_URL = 'https://artifacts.contentstack.com/regions.json'
+
+
+class Endpoint:
+    """
+    Resolves Contentstack service endpoint URLs for any supported region.
+
+    Usage::
+
+        from contentstack_management.endpoint import Endpoint
+
+        # Single service URL
+        url = Endpoint.get_contentstack_endpoint('eu', 'contentManagement')
+        # 'https://eu-api.contentstack.com'
+
+        # All services for a region
+        endpoints = Endpoint.get_contentstack_endpoint('azure-na')
+        # {'contentDelivery': '...', 'contentManagement': '...', ...}
+
+        # Strip scheme (useful when building endpoint strings manually)
+        host = Endpoint.get_contentstack_endpoint('gcp-eu', 'contentManagement', omit_https=True)
+        # 'gcp-eu-api.contentstack.com'
+    """
+
+    _regions_data = None  # in-memory cache — shared across all instances
+
+    @staticmethod
+    def get_contentstack_endpoint(region='us', service='', omit_https=False):
+        """
+        Resolve a Contentstack service endpoint URL for a given region.
+
+        :param region: Region ID or alias ('us', 'eu', 'azure-na', 'gcp-eu', etc.).
+                       Defaults to 'us' (AWS North America).
+        :param service: Service key ('contentDelivery', 'contentManagement', ...).
+                        When empty, returns a dict of all endpoints for the region.
+        :param omit_https: When True, strips 'https://' prefix from returned URL(s).
+        :returns: str when service is provided, dict[str,str] otherwise.
+        :raises ValueError: When region is empty, unknown, or service is not found.
+        :raises RuntimeError: When regions.json cannot be read or parsed.
+        """
+        if not region:
+            raise ValueError('Empty region provided. Please put valid region.')
+
+        data = Endpoint._load_regions()
+        normalized = region.strip().lower()
+        region_row = Endpoint._find_region(data['regions'], normalized)
+
+        if region_row is None:
+            raise ValueError(f'Invalid region: {region}')
+
+        if service:
+            if service not in region_row['endpoints']:
+                raise ValueError(
+                    f'Service "{service}" not found for region "{region_row["id"]}"'
+                )
+            url = region_row['endpoints'][service]
+            return Endpoint._strip_https(url) if omit_https else url
+
+        endpoints = region_row['endpoints']
+        if omit_https:
+            return {k: Endpoint._strip_https(v) for k, v in endpoints.items()}
+        return dict(endpoints)
+
+    @staticmethod
+    def _load_regions():
+        """
+        Load and cache regions.json.
+
+        Resolution order:
+          1. In-memory static cache (zero I/O after first call)
+          2. contentstack_management/data/regions.json on disk (written by download script)
+          3. Live download from artifacts.contentstack.com (fallback)
+        """
+        if Endpoint._regions_data is not None:
+            return Endpoint._regions_data
+
+        data_dir = os.path.join(os.path.dirname(__file__), 'data')
+        path = os.path.join(data_dir, 'regions.json')
+
+        if not os.path.exists(path):
+            Endpoint._download_and_save(path)
+
+        if not os.path.exists(path):
+            raise RuntimeError(
+                'contentstack-management: regions.json not found and could not be downloaded. '
+                'Run "python scripts/download_regions.py" and ensure network access.'
+            )
+
+        try:
+            with open(path, 'r', encoding='utf-8') as f:
+                decoded = json.load(f)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise RuntimeError(
+                f'contentstack-management: Could not read or parse regions.json: {exc}. '
+                'Run "python scripts/download_regions.py" to re-download it.'
+            ) from exc
+
+        if not isinstance(decoded, dict) or 'regions' not in decoded:
+            raise RuntimeError(
+                'contentstack-management: regions.json is corrupt. '
+                'Run "python scripts/download_regions.py" to re-download it.'
+            )
+
+        Endpoint._regions_data = decoded
+        return Endpoint._regions_data
+
+    @staticmethod
+    def _download_and_save(dest):
+        """
+        Download regions.json from the Contentstack CDN and save to disk.
+        Uses the requests library (already an SDK dependency).
+        Silent on failure — the caller decides whether a missing file is fatal.
+
+        :param dest: Absolute path to write the file to.
+        """
+        os.makedirs(os.path.dirname(dest), exist_ok=True)
+
+        try:
+            import requests
+            response = requests.get(REGIONS_URL, timeout=30)
+            response.raise_for_status()
+            data = response.text
+        except Exception:  # noqa: BLE001
+            return
+
+        try:
+            decoded = json.loads(data)
+        except json.JSONDecodeError:
+            return
+
+        if isinstance(decoded, dict) and 'regions' in decoded:
+            try:
+                with open(dest, 'w', encoding='utf-8') as f:
+                    f.write(data)
+            except OSError:
+                pass
+
+    @staticmethod
+    def _find_region(regions, input_str):
+        """
+        Find a region entry by its id or any alias (case-insensitive).
+
+        Two-pass: exact id match first, then alias[] scan — mirrors PHP implementation.
+
+        :param regions: list of region dicts from regions.json
+        :param input_str: already-lowercased input
+        :returns: region dict or None
+        """
+        for row in regions:
+            if row['id'] == input_str:
+                return row
+        for row in regions:
+            for alias in row.get('alias', []):
+                if alias.lower() == input_str:
+                    return row
+        return None
+
+    @staticmethod
+    def _strip_https(url):
+        """Strip the https:// (or http://) scheme from a URL string."""
+        return re.sub(r'^https?://', '', url)
+
+    @staticmethod
+    def reset_cache():
+        """Reset the internal region cache. Intended for testing only."""
+        Endpoint._regions_data = None

contentstack_management-1.10.0/contentstack_management/region_refresh.py

@@ -0,0 +1,81 @@
+"""
+Utility to pull the latest regions.json from the Contentstack CDN and
+overwrite the bundled copy at contentstack_management/data/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_management 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__), "data", "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 data 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_management/data/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()
+        return 0
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(_cli_main())

{contentstack_management-1.9.0 → contentstack_management-1.10.0}/contentstack_management.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contentstack-management
-Version: 1.9.0
+Version: 1.10.0
 Summary: Contentstack API Client Library for Python
 Home-page: https://github.com/contentstack/contentstack-management-python
 Author: dev-ex

{contentstack_management-1.9.0 → contentstack_management-1.10.0}/contentstack_management.egg-info/SOURCES.txt

@@ -8,6 +8,8 @@ contentstack_management/_errors.py
 contentstack_management/_messages.py
 contentstack_management/common.py
 contentstack_management/contentstack.py
+contentstack_management/endpoint.py
+contentstack_management/region_refresh.py
 contentstack_management.egg-info/PKG-INFO
 contentstack_management.egg-info/SOURCES.txt
 contentstack_management.egg-info/dependency_links.txt

{contentstack_management-1.9.0 → contentstack_management-1.10.0}/setup.py

@@ -1,6 +1,21 @@
 import os
 import re
+import sys
 from setuptools import setup, find_packages
+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_management.region_refresh import refresh_regions
+            refresh_regions()
+        except Exception as exc:
+            print(f"WARNING: Could not refresh regions.json: {exc}", file=sys.stderr)
+        super().run()
 
 with open("README.md", "r") as f:
     long_description = f.read()
@@ -33,9 +48,11 @@ def get_author_email(package):
                      init_py, re.MULTILINE).group(1)
 
 setup(
+    cmdclass={"build_py": BuildPyWithRegions},
     name="contentstack-management",
     version=get_version(package),
     packages=find_packages(exclude=['tests']),
+    package_data={'contentstack_management': ['data/regions.json']},
     py_modules=['_api_client', 'contentstack','common','_errors','_constant'],
     description="Contentstack API Client Library for Python",
     long_description=long_description,