Merge branch 'development' into enh/dx-7324

Author: OMpawar-21

.cursor/rules/README.md

@@ -1,16 +1,5 @@
-# Cursor Rules — Contentstack Python CDA SDK
+# Cursor (optional)
 
-This repository keeps **project guidance in [skills](../../skills/)** (one folder per topic, each with **`SKILL.md`**), not as separate rule files under `.cursor/rules/`.
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
 
-## Where to look
-
-| Topic | Skill |
-|-------|--------|
-| PR checklist, public API, semver | [`skills/code-review/SKILL.md`](../../skills/code-review/SKILL.md) |
-| Branch, install, tests, versioning | [`skills/dev-workflow/SKILL.md`](../../skills/dev-workflow/SKILL.md) |
-| **Stack**, queries, CDA features | [`skills/contentstack-utils/SKILL.md`](../../skills/contentstack-utils/SKILL.md) |
-| **requests**, retries, **HTTPSConnection** | [`skills/framework/SKILL.md`](../../skills/framework/SKILL.md) |
-| Python layout and package conventions | [`skills/python-style/SKILL.md`](../../skills/python-style/SKILL.md) |
-| **pytest**, **`tests/`**, **`config.py`** | [`skills/testing/SKILL.md`](../../skills/testing/SKILL.md) |
-
-**Index:** [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

.github/workflows/issues-jira.yml

@@ -118,3 +118,4 @@ venv.bak/
 .mypy_cache/
 .idea/
 .vscode/
+*/assets/regions.json

.gitignore

@@ -1,49 +1,50 @@
-# AGENTS.md — AI / automation context
+# Contentstack Python CDA SDK – Agent guide
 
-## Project
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-| | |
-|---|---|
-| **Name** | **Contentstack** (PyPI) — **Python Content Delivery SDK** |
-| **Purpose** | Python client for the **Content Delivery API (CDA)**: **Stack**, content types, entries, assets, queries, live preview, taxonomy, variants. Uses **`requests`** + **`urllib3.Retry`** via **`HTTPSConnection`**. |
-| **Repository** | [contentstack/contentstack-python](https://github.com/contentstack/contentstack-python.git) |
+## What this repo is
+
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack/contentstack-python](https://github.com/contentstack/contentstack-python) |
+| **Purpose:** | Python client for the **Content Delivery API (CDA)**: stacks, content types, entries, assets, queries, live preview, taxonomy, and variants. Uses **`requests`** + **`urllib3.Retry`** via **`HTTPSConnection`**. |
+| **Out of scope:** | Content management (create / update / delete) — use `contentstack-management-python` for CMA operations. |
 
-## Tech stack
+## Tech stack (at a glance)
 
 | Area | Details |
 |------|---------|
-| **Language** | **Python** (see **`setup.py`** `python_requires`, classifiers) |
-| **HTTP** | **`requests`**, **`urllib3`** |
-| **Tests** | **pytest** + **`unittest.TestCase`** under **`tests/`** |
-| **Packaging** | **`setuptools`** / **`setup.py`**, package **`contentstack`** |
+| Language | Python ≥ 3.6 (`setup.py` `python_requires`) |
+| Build | `setuptools` / `setup.py`; package `contentstack` |
+| Tests | `pytest` — `tests/test_*.py`; config in `tests/pytest.ini` |
+| Lint / coverage | `ruff`, `flake8`, `black`, `isort`; `pytest-cov` for coverage |
+| HTTP | `requests`, `urllib3` |
 
-## Source layout
+## Commands (quick reference)
 
-| Path | Role |
-|------|------|
-| `contentstack/stack.py` | **`Stack`**, **`ContentstackRegion`**, endpoint and **HTTPSConnection** wiring |
-| `contentstack/https_connection.py`, `contentstack/controller.py` | Session, retries, **`get_request`** |
-| `contentstack/query.py`, `contentstack/basequery.py` | Queries |
-| `contentstack/entry.py`, `asset.py`, `contenttype.py`, … | Domain modules |
-| `contentstack/__init__.py` | Public exports (**`Stack`**, **`Entry`**, **`Asset`**, …), **`__version__`** |
-| `config.py` (repo root) | Test credentials and UIDs — **must not commit secrets** |
-| `tests/*.py` | Integration-style tests importing **`config`** |
-
-## Common commands
+| Command Type | Command |
+|---|---|
+| Build | `pip install -e .` |
+| Install deps | `pip install -r requirements.txt` |
+| Test | `pytest tests/` |
+| Coverage | `pytest --cov=contentstack tests/` |
+| Lint | `ruff check contentstack/` |
 
-```bash
-pip install -r requirements.txt
-pip install -e .
-pytest tests/
-```
+CI: [`.github/workflows/python-publish.yml`](.github/workflows/python-publish.yml) · [`.github/workflows/check-branch.yml`](.github/workflows/check-branch.yml)
 
-## Environment / test configuration
+## Where the documentation lives: skills
 
-Tests load stack settings from root **`config.py`** (e.g. **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**). Use a local, gitignored file or sanitized values for CI. Do not commit secrets.
+| Skill | Path | What it covers |
+|---|---|---|
+| Development workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Install, tests, `config.py`, versioning, PR baseline |
+| Contentstack CDA SDK | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | `Stack`, queries, entries, assets, live preview, taxonomy, HTTP session |
+| Python style & repo layout | [`skills/python-style/SKILL.md`](skills/python-style/SKILL.md) | Package layout, `setup.py`, naming conventions, no secret logging |
+| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | `pytest`, `tests/`, `config.py`, credential hygiene |
+| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist, public API, `Stack`, HTTP layer, secrets |
+| Framework / HTTP | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | `requests`, `HTTPSConnection`, `urllib3` retries, timeouts |
 
-## Further guidance
+An index with "when to use" hints is in [`skills/README.md`](skills/README.md).
 
-- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
-- **Skills:** [`skills/README.md`](skills/README.md)
+## Using Cursor (optional)
 
-Product docs: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

AGENTS.md

@@ -1,11 +1,32 @@
 # CHANGELOG
 
-## _v2.6.0_
+## _v2.7.0_
 
-### **Date: 18-May-2026**
+### **Date: 20-July-2026**
 
 - Added optional branch support for entry variants on `Entry.variants()` and `ContentType.variants()`.
 
+## _v2.6.1_
+
+### **Date: 13-July-2026**
+
+- Removed unused `keyring` dependency to resolve a Snyk license-policy issue on the transitive `secretstorage` package.(Snyk Fix)
+
+## _v2.6.0_
+
+### **Date: 22-June-2026**
+
+- Dynamic endpoint resolution via new `Endpoint` class.
+- Region-to-URL mapping is now loaded from a bundled `regions.json` (sourced from `artifacts.contentstack.com`) instead of hardcoded `if/elif` chains.
+- Added `Endpoint.get_contentstack_endpoint(region, service, omit_https)` — resolves any supported region to its `contentDelivery`, `contentManagement`, or other service URL.
+- Added `contentstack.get_contentstack_endpoint()` module-level proxy.
+- `Stack` now auto-resolves `host` and `live_preview` management host via `Endpoint` on initialization.
+- Bundled `contentstack/assets/regions.json` included in `package_data` — always present after `pip install`.
+- `setup.py` auto-refreshes `regions.json` at build time via a custom `BuildPyWithRegions` command; network failures warn but never block the build.
+- Runtime fallback: if `regions.json` is absent, the SDK downloads it live on the first `Endpoint` call.
+- Added `refresh_regions()` utility to programmatically download the latest regions manifest from the Contentstack CDN and overwrite the bundled `assets/regions.json` (`from contentstack import refresh_regions`).
+- Added `python3 -m contentstack.region_refresh` CLI command for refreshing the registry after `pip install` (source-tree script `scripts/download_regions.py` is for contributors only).
+
 ## _v2.5.1_
 
 ### **Date: 15-April-2026**

CHANGELOG.md

@@ -6,23 +6,43 @@
 from .entry import Entry
 from .asset import Asset
 from .contenttype import ContentType
+from .endpoint import Endpoint
 from .https_connection import HTTPSConnection
 from contentstack.stack import Stack
 from .utility import Utils
+from .region_refresh import refresh_regions
 
 __all__ = (
 "Entry",
 "Asset",
 "ContentType",
+"Endpoint",
 "HTTPSConnection",
 "Stack",
-"Utils"
+"Utils",
+"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-delivery-python'
 __author__ = 'contentstack'
 __status__ = 'debug'
-__version__ = 'v2.6.0'
+__version__ = 'v2.7.0'
 __endpoint__ = 'cdn.contentstack.io'
 __email__ = 'support@contentstack.com'
 __developer_email__ = 'mobile@contentstack.com'

contentstack/__init__.py

@@ -7,6 +7,7 @@
 
 # ************* Module ContentType **************
 # Your code has been rated at 10.00/10 by pylint
+from __future__ import annotations
 import json
 import logging
 from urllib import parse