contentstack · cs-raj · Jun 16, 2026 · May 13, 2026 · May 13, 2026 · May 13, 2026
@@ -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.
@@ -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.
@@ -11,6 +11,17 @@
 - `Stack` now auto-resolves `host` and `live_preview` management host via `Endpoint` on initialization.
 - Added `scripts/download_regions.py` to pre-populate `regions.json` at install time.
 - Runtime fallback: if `regions.json` is absent, the SDK downloads it live on first use.
+## _v2.5.3_
+
+### **Date: 08-June-2026**
+
+- Fixed security issues.
+
+## _v2.5.2_
+
+### **Date: 18-May-2026**
+
+- Bumped urllib3 in development requirements to address reported vulnerabilities.
 
 ## _v2.5.1_
 

@@ -51,14 +51,14 @@ Pygments~=2.20.0
 wrapt==1.16.0
 certifi==2024.8.30
 oauthlib==3.2.2
-idna==3.10
+idna==3.15
 chardet~=5.2.0
 alabaster==0.7.16
 zipp==3.20.1
 distlib~=0.3.8
 cachetools~=5.4.0
 tomlkit~=0.13.2
-urllib3~=2.6.3
+urllib3~=2.7.0
 exceptiongroup~=1.2.2
 iniconfig~=2.0.0
 pytest-cov>=4.0.0

@@ -1,12 +1,16 @@
-# Project skills — Contentstack Python CDA SDK
-
-| Skill | When to use |
-|-------|-------------|
-| [`code-review/`](code-review/SKILL.md) | PR review, semver, public API on **Stack** |
-| [`contentstack-utils/`](contentstack-utils/SKILL.md) | **Stack**, queries, entries, assets, live preview, CDA behavior |
-| [`dev-workflow/`](dev-workflow/SKILL.md) | Branch/PR, install, tests, **config.py**, versioning |
-| [`framework/`](framework/SKILL.md) | **requests**, **HTTPSConnection**, retries |
-| [`python-style/`](python-style/SKILL.md) | **`contentstack/`** layout, **setup.py**, Python conventions |
-| [`testing/`](testing/SKILL.md) | **pytest** + **`tests/`** + **`config.py`** |
-
-**Overview:** [`AGENTS.md`](../AGENTS.md) · **Cursor rules index:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)
+# Skills – Contentstack Python CDA SDK
+
+Source of truth for detailed guidance. Read **[`AGENTS.md`](../AGENTS.md)** first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+|---|---|
+| `dev-workflow` | Setting up locally, running tests, bumping the version, or before a PR |
+| `contentstack-utils` | Working with `Stack`, queries, entries, assets, live preview, taxonomy, or variants |
+| `python-style` | Editing `contentstack/` modules or `setup.py` — layout, naming, conventions |
+| `testing` | Adding or changing tests under `tests/`, managing `config.py`, credential hygiene |
+| `code-review` | PR checklist, API semver, HTTP regressions, secrets audit |
+| `framework` | Changing `HTTPSConnection`, retries, `urllib3` usage, or `requests` session config |
+
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).
@@ -1,40 +1,45 @@
 ---
 name: code-review
-description: PR review for Contentstack Python CDA SDK — public API, Stack, HTTP layer, tests.
+description: Use when reviewing PRs for the Python CDA SDK — public API, Stack, HTTP layer, tests, secrets.
 ---
 
-# Code review — Contentstack Python CDA SDK
+# Code review – Contentstack Python CDA SDK
 
-## Checklist
+## When to use
 
-- [ ] **API:** New or changed **`Stack`** / content-type / query / entry methods documented; **`contentstack/__init__.py`** exports updated if needed.
-- [ ] **Version:** **`__version__`** in **`contentstack/__init__.py`** aligned with release strategy for breaking changes.
-- [ ] **HTTP:** **`https_connection.py`** / **`controller.py`** changes keep retry and timeout behavior predictable.
-- [ ] **Tests:** **`pytest tests/`** passes; extend **`tests/`** when CDA behavior changes.
-- [ ] **Secrets:** No tokens in repo; **`config.py`** remains local-only when it holds real credentials.
+- Reviewing a PR, self-review before submit, or running an automated review pass.
 
-## Public API
+## Instructions
 
-- **Exported** **`Stack`**, **ContentType**, **Query**, asset/entry helpers match **README** and consumer expectations; **`contentstack/__init__.py`** **`__all__`** stays accurate when exports change.
-- **Docstrings** on **`Stack`** and key public methods when behavior or options change.
+### Checklist
 
-## Compatibility
+- [ ] **API:** New or changed `Stack` / content-type / query / entry methods documented; `contentstack/__init__.py` exports updated if needed.
+- [ ] **Version:** `__version__` in `contentstack/__init__.py` aligned with release strategy for breaking changes.
+- [ ] **HTTP:** `https_connection.py` / `controller.py` changes keep retry and timeout behavior predictable.
+- [ ] **Tests:** `pytest tests/` passes; extend `tests/` when CDA behavior changes.
+- [ ] **Secrets:** No tokens in repo; `config.py` remains local-only when it holds real credentials.
 
-- Avoid breaking **`Stack.__init__`** signatures or method chains without a semver strategy; document migration for breaking changes (**`setup.py`** / **`__version__`**).
+### Public API
 
-## HTTP / dependencies
+- Exported `Stack`, `ContentType`, `Query`, asset/entry helpers match `README` and consumer expectations; `contentstack/__init__.py` `__all__` stays accurate when exports change.
+- Docstrings on `Stack` and key public methods when behavior or options change.
 
-- Changes to **`requests`**, **retry** behavior, or **`HTTPSConnection`** should stay consistent with **`contentstack/controller.py`** and **`urllib3`** **`Retry`** usage in **`stack.py`**.
+### Compatibility
 
-## Tests
+- Avoid breaking `Stack.__init__` signatures or method chains without a semver strategy; document migration for breaking changes in `setup.py` / `__version__`.
 
-- **Tests** hit the live CDA when using **`config`** credentials; extend **`tests/`** when request/response behavior changes. Do not commit new secrets.
+### HTTP / dependencies
 
-## Security
+- Changes to `requests`, retry behavior, or `HTTPSConnection` should stay consistent with `contentstack/controller.py` and `urllib3.Retry` usage in `stack.py`.
 
-- No hardcoded tokens in source or docs; no logging of **api keys**, **delivery tokens**, **preview**, or **management** tokens.
+### Security
 
-## References
+- No hardcoded tokens in source or docs; no logging of `api_key`, `delivery_token`, `preview_token`, or `management_token`.
 
-- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)
-- [`python-style/SKILL.md`](../python-style/SKILL.md)
+### Severity (optional)
+
+| Level | Examples |
+|-------|----------|
+| **Blocker** | Breaking public API without approval; security issue; no tests for new logic |
+| **Major** | Inconsistent HTTP/retry behavior; README examples that don't match code |
+| **Minor** | Style; minor docs |
@@ -1,43 +1,43 @@
 ---
 name: contentstack-utils
-description: Contentstack Python CDA SDK — Stack, queries, entries, assets, live preview, taxonomy, HTTP session.
+description: Use for Stack initialization, queries, entries, assets, live preview, taxonomy, and variants in contentstack-python.
 ---
 
-# Contentstack Python Delivery SDK (`contentstack/`)
+# Contentstack CDA SDK – Contentstack Python CDA SDK
 
-## Stack entry
+## When to use
 
-- **`Stack`** in **`contentstack/stack.py`**: validates **api_key**, **delivery_token**, **environment**; resolves **region → host** via **`ContentstackRegion`**; builds **`endpoint`**; wires **`HTTPSConnection`** with **headers**, **timeout**, **`urllib3.Retry`**, and optional **`live_preview`** / **`branch`** / **`early_access`**.
+- Implementing or changing `Stack`, content-type, query, entry, or asset behavior.
+- Working with live preview, taxonomy, global fields, variants, or image transforms.
+- Assessing CDA API alignment or extending the public SDK surface.
 
-## Features
+## Instructions
 
-- **Content types & entries** — **`contenttype.py`**, **`entry.py`**, **`entryqueryable.py`**.
-- **Queries** — **`basequery.py`**, **`query.py`**; chain methods align with CDA query parameters.
-- **Assets** — **`asset.py`**, **`assetquery.py`**.
-- **Taxonomy, global fields, variants, image transform** — **`taxonomy.py`**, **`globalfields.py`**, **`variants.py`**, **`image_transform.py`**.
-- **Sync** — **`Stack.sync_init`**, **`pagination`**, **`sync_token`** → **`/stacks/sync`** via **`__sync_request`**.
+### Stack entry
 
-## Live preview
+- **`Stack`** in `contentstack/stack.py`: validates `api_key`, `delivery_token`, `environment`; resolves `region → host` via `ContentstackRegion`; builds `endpoint`; wires `HTTPSConnection` with `headers`, `timeout`, `urllib3.Retry`, and optional `live_preview` / `branch` / `early_access`.
 
-- **`live_preview`** dict (**enable**, **host**, **authorization**, etc.) merged in **`deep_merge_lp.py`** / stack setup; keep behavior aligned with **`tests/test_live_preview.py`**.
+### Features
 
-## HTTP layer
+- **Content types & entries** — `contenttype.py`, `entry.py`, `entryqueryable.py`.
+- **Queries** — `basequery.py`, `query.py`; chain methods align with CDA query parameters.
+- **Assets** — `asset.py`, `assetquery.py`.
+- **Taxonomy, global fields, variants, image transform** — `taxonomy.py`, `globalfields.py`, `variants.py`, `image_transform.py`.
+- **Sync** — `Stack.sync_init`, `pagination`, `sync_token` → `/stacks/sync` via `__sync_request`.
 
-- **`https_connection.py`** — **`requests.Session`**, **`HTTPAdapter`**, **`get_request`** from **`controller.py`**; user-agent uses **`contentstack.__title__`** / **`__version__`**.
+### Live preview
 
-## Extending
+- `live_preview` dict (`enable`, `host`, `authorization`, etc.) merged in `deep_merge_lp.py` / stack setup; keep behavior aligned with `tests/test_live_preview.py`.
 
-- Add query or stack methods consistent with [CDA query parameters](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
-- Keep transport logic in **`HTTPSConnection`** / **`controller`** rather than duplicating **`requests`** setup.
-
-## Dependencies
+### HTTP layer
 
-- **`requests`**, **`urllib3`** (**Retry**), **`python-dateutil`**
+- `https_connection.py` — `requests.Session`, `HTTPAdapter`, `get_request` from `controller.py`; user-agent uses `contentstack.__title__` / `__version__`.
 
-## Related skills
+### Extending
 
-- [`framework/SKILL.md`](../framework/SKILL.md) — retries, **`HTTPAdapter`**, timeouts
+- Add query or stack methods consistent with [CDA query parameters](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
+- Keep transport logic in `HTTPSConnection` / `controller` rather than duplicating `requests` setup.
 
-## Docs
+### Dependencies
 
-- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
+- `requests`, `urllib3` (`Retry`), `python-dateutil`
@@ -1,20 +1,35 @@
 ---
 name: dev-workflow
-description: Branches, install, tests, and versioning for contentstack-python.
+description: Use for install, pytest, versioning, pre-commit hooks, and PR baseline in contentstack-python.
 ---
 
-# Development workflow — Contentstack Python CDA SDK
+# Development workflow – Contentstack Python CDA SDK
 
-## Before a PR
+## When to use
 
-1. **Install** — `pip install -r requirements.txt` and editable package as needed: `pip install -e .`
-2. **Tests** — `pytest tests/` (or `python -m pytest tests/`) from the repo root; **`tests/pytest.ini`** applies.
-3. **Integration tests** use **`config.py`** at repo root for **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**, etc. Use local credentials only; **never commit** real tokens—prefer a gitignored local **`config.py`** or environment-based loading if you refactor tests.
+- Setting up locally, opening a PR, or matching CI expectations.
+- Answering "how do we run tests?" or "what runs in CI?"
+- Bumping the SDK version for a release.
 
-## Versioning
+## Instructions
 
-- Bump **`contentstack/__init__.py`** **`__version__`** and **`setup.py`**-driven releases per semver for user-visible SDK changes.
+### Branches & releases
 
-## References
+- **Flow:** feature / fix branches → `staging` → `master`. Direct PRs to `master` from feature branches are rejected by [`.github/workflows/check-branch.yml`](../../.github/workflows/check-branch.yml).
+- **PyPI:** publish a **GitHub Release** to trigger [`.github/workflows/python-publish.yml`](../../.github/workflows/python-publish.yml).
 
-- [`AGENTS.md`](../../AGENTS.md) · [`contentstack-utils/SKILL.md`](../contentstack-utils/SKILL.md)
+### Before a PR
+
+1. **Install** — `pip install -r requirements.txt` then `pip install -e .` for an editable install.
+2. **Tests** — `pytest tests/` (or `python -m pytest tests/`) from the repo root; `tests/pytest.ini` applies.
+3. **Integration tests** use `config.py` at repo root for `HOST`, `APIKEY`, `DELIVERYTOKEN`, `ENVIRONMENT`, etc. Use local credentials only; **never commit** real tokens.
+
+### Versioning
+
+- Bump `__version__` in `contentstack/__init__.py` per semver for any user-visible SDK change.
+
+### Pre-commit hooks
+
+- **Talisman** — scans for secrets before commit (`.talismanrc`).
+- **Snyk** — dependency vulnerability check (`snyk test --all-projects --fail-on=all`).
+- Both hooks are in `.husky/pre-commit`. Skip with `SKIP_HOOK=1` only when justified.