diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md index 0c75565..f5c1f87 100644 --- a/.cursor/rules/README.md +++ b/.cursor/rules/README.md @@ -1,5 +1,5 @@ # Cursor (optional) -**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool). +**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**. -This folder only points contributors here so nothing editor-specific duplicates the canonical docs. +This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs. diff --git a/AGENTS.md b/AGENTS.md index 3ba6617..77c1895 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,24 +1,24 @@ -# Contentstack Management Python — Agent guide +# Contentstack Management Python – Agent guide -**Universal entry point** for anyone automating or assisting work in this repo—AI agents (Cursor, Copilot, CLI tools), reviewers, and contributors. Conventions and detailed guidance live in **`skills/*/SKILL.md`**, not in editor-specific config, so the same instructions apply whether or not you use Cursor. +**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**. ## What this repo is -| | | -|---|---| -| **Name** | **`contentstack-management`** (PyPI) — **Contentstack Management Python SDK** | -| **Purpose** | Python client for the **Content Management API (CMA)**: organizations, stacks, content types, entries, assets, webhooks, workflows, OAuth, and related resources. Uses **`requests`** via **`_APIClient`**. | -| **Repository** | [contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python.git) | +| Field | Detail | +|--------|--------| +| **Name:** | **`contentstack-management`** (PyPI) — [contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python) | +| **Purpose:** | Python client for the **Content Management API (CMA)**: organizations, stacks, content types, entries, assets, webhooks, workflows, OAuth, and related resources. Uses **`requests`** via **`_APIClient`**. | -## Tech stack +## Tech stack (at a glance) | Area | Details | |------|---------| -| **Language** | **Python** ≥ 3.9 (`setup.py` `python_requires`) | -| **HTTP** | **`requests`**, **`requests-toolbelt`**, **`urllib3`** | -| **Tests** | **pytest** — **`tests/unit`**, **`tests/api`**, **`tests/mock`** | -| **Lint** | **pylint** (see `requirements.txt`) | -| **Secrets / hooks** | **Talisman**, **Snyk** (see **README.md** development setup) | +| Language | Python ≥ 3.9 (`setup.py` `python_requires`) | +| Build | `setuptools` / `setup.py`; package `contentstack_management` | +| HTTP | `requests`, `requests-toolbelt`, `urllib3` | +| Tests | `pytest` — `tests/unit`, `tests/api`, `tests/mock` | +| Lint / coverage | `pylint`, `coverage` (see `requirements.txt`) | +| Secrets / hooks | Talisman, Snyk (see `README.md` development setup) | ## Source layout @@ -33,16 +33,14 @@ ## Commands (quick reference) -```bash -pip install -e ".[dev]" -# or: pip install -r requirements.txt && pip install pytest pytest-cov - -pytest tests/unit/ -v -pytest tests/api/ -v # live CMA — needs .env (see tests/cred.py) -pytest tests/mock/ -v -pytest tests/ -v -coverage run -m pytest tests/unit/ -``` +| Command Type | Command | +|---|---| +| Install | `pip install -e ".[dev]"` | +| Test (unit) | `pytest tests/unit/ -v` | +| Test (API, live) | `pytest tests/api/ -v` (needs `.env` — see `tests/cred.py`) | +| Test (mock) | `pytest tests/mock/ -v` | +| Coverage | `coverage run -m pytest tests/unit/` | +| Lint | `pylint contentstack_management/` | ## Environment variables (API / integration tests) @@ -50,9 +48,7 @@ Loaded via **`tests/cred.py`** (`load_dotenv()`). Examples include **`HOST`**, * Do not commit secrets. -## Where the real documentation lives: skills - -Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review: +## Where the documentation lives: skills | Skill | Path | What it covers | |-------|------|----------------| @@ -63,10 +59,10 @@ Read these **`SKILL.md` files** for full conventions—**this is the source of t | **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist—public API, HTTP/auth, tests, security | | **Framework / HTTP** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | **`requests`**, retries, OAuth interceptor, where to change transport | -An index with short “when to use” hints is in [`skills/README.md`](skills/README.md). +An index with “when to use” hints is in [`skills/README.md`](skills/README.md). -## Using Cursor +## Using Cursor (optional) -If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same source of truth as everyone else; no separate `.mdc` rule files. +If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else. Product docs: [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/). diff --git a/skills/README.md b/skills/README.md index 2d7c58a..ef2eea6 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,6 +1,6 @@ -# Skills — Contentstack Management Python +# Skills – Contentstack Management Python -**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, HTTP layer). Read **`AGENTS.md`** at the repo root for the index and quick commands; each skill is a folder with **`SKILL.md`** (YAML frontmatter: `name`, `description`). +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 @@ -13,7 +13,4 @@ | **code-review** | PR checklist, API semver, HTTP regressions, secrets | | **framework** | Changing **`_APIClient`**, retries, **`requests`** usage, OAuth interceptor wiring | -## How to use these docs - -- **Humans / any AI tool:** Start at **`AGENTS.md`**, then open the relevant **`skills//SKILL.md`**. -- **Cursor users:** **`.cursor/rules/README.md`** only points to **`AGENTS.md`** so guidance stays universal—no duplicate `.mdc` rule sets. +Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`). diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 46b7181..b8e2bb4 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,9 +1,9 @@ --- name: code-review -description: PR checklist—public API, Client/Stack, _APIClient/OAuth, tests, secrets; align with README and exports. +description: Use when reviewing PRs for the Management Python SDK — public API, _APIClient, OAuth, tests, security. --- -# Code review — Contentstack Management Python +# Code review – Contentstack Management Python ## When to use @@ -42,9 +42,3 @@ Work through the checklist below. Optionally tag findings: **Blocker**, **Major* | **Blocker** | Breaking public API without approval; security issue; no tests for new logic where tests are practical | | **Major** | Inconsistent HTTP/auth behavior; README examples that do not match code | | **Minor** | Style; minor docs | - -## References - -- **`skills/testing/SKILL.md`** -- **`skills/contentstack-management/SKILL.md`** -- **`skills/dev-workflow/SKILL.md`** diff --git a/skills/contentstack-management/SKILL.md b/skills/contentstack-management/SKILL.md index e49f557..4cb5285 100644 --- a/skills/contentstack-management/SKILL.md +++ b/skills/contentstack-management/SKILL.md @@ -1,9 +1,9 @@ --- name: contentstack-management -description: Public CMA surface—Client, Stack, _APIClient, domain resources, OAuth; align with CMA docs and semver. +description: Use for Client, Stack, _APIClient, domain resources, OAuth, and CMA API alignment. --- -# Contentstack Management — SDK skill +# Contentstack Management SDK – Contentstack Management Python ## When to use @@ -11,33 +11,29 @@ description: Public CMA surface—Client, Stack, _APIClient, domain resources, O - Updating **`README.md`** or public exports for user-visible behavior. - Assessing semver impact of constructor, method, or export changes. -## Main entry (consumer API) +## Instructions + +### Main entry (consumer API) - **`contentstack_management.Client`** in **`contentstack.py`**: builds CMA **endpoint** from **region** / **host** / **scheme**, merges **headers** (**authtoken**, **management_token**, **early_access**), constructs **`_APIClient`**, optional **`oauth_config`** with **`OAuthHandler`**. -## Structure +### Structure - **`Stack`** — **`contentstack_management/stack/stack.py`**: stack-scoped resources (content types, entries, assets, branches, webhooks, …). - **Org / user** — **`organizations/`**, **`users/`**, **`user_session/`** as applicable. - **Resources** — packages under **`contentstack_management/`** following existing patterns. - **OAuth** — **`oauth/oauth_handler.py`**, **`oauth/oauth_interceptor.py`**; keep aligned with **`_APIClient`** request path. -## HTTP layer +### HTTP layer - **`_APIClient._call_request`** — central place for method, URL, JSON, files; respect **timeout** and **max_retries**. -## Extending +### Extending - Add methods on the appropriate resource class; align path and payload shapes with **CMA** docs. - Prefer routing HTTP through **`_APIClient`** for consistent retries and OAuth handling. -## Docs and versioning +### Docs and versioning - Exported **`Client`**, **`Region`**, and stack helpers should match **README** and **`contentstack_management.__init__.py`**. - Document migration for intentional breaking changes. - -## References - -- [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/) -- **`skills/framework/SKILL.md`** -- **`skills/python-style/SKILL.md`** diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md index 0ed0d4b..0762bcd 100644 --- a/skills/dev-workflow/SKILL.md +++ b/skills/dev-workflow/SKILL.md @@ -1,44 +1,40 @@ --- name: dev-workflow -description: Install, pytest unit/API/mock, versioning, pylint, hooks—standard workflow for this SDK repo. +description: Use for install, pytest suites, versioning, pylint, hooks, and PR baseline in contentstack-management-python. --- -# Development workflow — Contentstack Management Python +# Development workflow – Contentstack Management Python ## When to use - Setting up locally, opening a PR, or matching CI expectations. -- Answering “how do we run tests?” or “what runs in CI?” +- Answering "how do we run tests?" or "what runs in CI?" -## Branches & releases +## Instructions + +### Branches & releases - **Flow:** merge work to **`development`**; **release PRs** are **`development` → `main`**. After **`main`** moves, [`.github/workflows/back-merge-pr.yml`](../../.github/workflows/back-merge-pr.yml) can open **`main` → `development`** to resync. - **PyPI:** publish a **GitHub Release** (`release: published`) to run [`.github/workflows/release.yml`](../../.github/workflows/release.yml). PRs that touch **`contentstack_management/`** or **`setup.py`** must bump **`__version__`** and **`CHANGELOG.md`** per [`.github/workflows/check-version-bump.yml`](../../.github/workflows/check-version-bump.yml). -## Before a PR +### Before a PR 1. **Install** — `pip install -e ".[dev]"` or install **`requirements.txt`** plus **pytest** / **pytest-cov** as needed. 2. **`pytest tests/unit/`** — required baseline (matches CI **`coverage run -m pytest tests/unit/`**). 3. **API tests** — `pytest tests/api/` when your change affects live CMA behavior; configure **`.env`** per **`tests/cred.py`**. Never commit tokens. 4. **Mock tests** — `pytest tests/mock/` when extending mocked HTTP or fixtures. -## Packaging +### Packaging - Bump **`contentstack_management/__init__.py`** **`__version__`** and align **`setup.py`** versioning if release-facing. -## Tooling +### Tooling - **pylint** is listed in **`requirements.txt`**; follow existing style in touched files. - **Husky / Talisman / Snyk** — see **README.md** for local hook setup. -## Pull requests +### Pull requests - Build passes: **`pytest tests/unit/`** at minimum; run **API** / **mock** when your change touches those layers. - Follow **`skills/code-review/SKILL.md`** before merge. - Prefer backward-compatible public API; call out breaking changes and semver. - -## References - -- **`AGENTS.md`** -- **`skills/contentstack-management/SKILL.md`** -- **`skills/testing/SKILL.md`** diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md index 6046c5b..8f44ff2 100644 --- a/skills/framework/SKILL.md +++ b/skills/framework/SKILL.md @@ -1,31 +1,27 @@ --- name: framework -description: requests-based _APIClient, retries, timeout, OAuth interceptor—central HTTP for the Management SDK. +description: Use for _APIClient, requests usage, retries, timeout, and OAuth interceptor in contentstack-management-python. --- -# Framework / HTTP — Contentstack Management Python +# Framework / HTTP – Contentstack Management Python ## When to use - Editing **`contentstack_management/_api_client.py`** or OAuth interceptor/handler wiring. - Changing retry policy, timeouts, or how **`requests`** is invoked. -## Integration point +## Instructions + +### Integration point - **`_APIClient`** uses **`requests`** in **`_call_request`**, honors **timeout** and **max_retries**, and delegates to **`oauth_interceptor`** when configured. -## When to change +### When to change - **Retry or transport behavior** — keep logic centralized in **`_APIClient`** unless a resource truly needs a documented exception. - **Auth headers** — prefer extending **`Client`** / **`user_agents`** patterns rather than scattering header merges. -## Testing +### Testing - **Unit** — mock **`requests`** or **`_APIClient`** at the boundary used by existing tests. - **API** — full stack via credentials from **`tests/cred.py`**. - -## References - -- **`skills/contentstack-management/SKILL.md`** -- **`skills/dev-workflow/SKILL.md`** -- **`skills/testing/SKILL.md`** diff --git a/skills/python-style/SKILL.md b/skills/python-style/SKILL.md index d6ebb5f..d91ed70 100644 --- a/skills/python-style/SKILL.md +++ b/skills/python-style/SKILL.md @@ -1,37 +1,33 @@ --- name: python-style -description: Package layout under contentstack_management/, setup.py, pylint-friendly style, imports, no secret logging. +description: Use for package layout under contentstack_management/, setup.py, pylint-friendly style, and imports. --- -# Python style and repo layout — Contentstack Management Python +# Python style and repo layout – Contentstack Management Python ## When to use - Editing any Python under **`contentstack_management/`**, **`setup.py`**, or **`requirements.txt`**. - Adding modules or changing how the public package surface is exported. -## Layout +## Instructions + +### Layout - **`contentstack_management/contentstack.py`** — **`Client`**, **`Region`**, **`user_agents`**, OAuth wiring. - **`contentstack_management/_api_client.py`** — **`_APIClient`** (HTTP, retries). - **`contentstack_management/stack/`** — stack-scoped API surface. - **Domain modules** — **`entries/`**, **`assets/`**, **`webhooks/`**, **`oauth/`**, etc. -## Style +### Style - Match existing modules: naming, docstrings, and patterns already used in the same directory. - Prefer small, focused changes; keep **`__init__.py`** exports consistent with public API intent (**`README`**, **`contentstack_management.__all__`**). -## Imports +### Imports - Use **`requests`** (and **`requests-toolbelt`** where already used) through **`_APIClient`** patterns rather than ad-hoc clients in domain modules unless justified. -## Security +### Security - Do not log **authtokens**, **management tokens**, **passwords**, or **API keys**; preserve existing header handling in **`Client`**. - -## References - -- **`skills/framework/SKILL.md`** -- **`skills/contentstack-management/SKILL.md`** -- **`skills/testing/SKILL.md`** diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md index b583fa0..9b7fca0 100644 --- a/skills/testing/SKILL.md +++ b/skills/testing/SKILL.md @@ -1,16 +1,18 @@ --- name: testing -description: pytest—unit, API, mock; tests/cred.py and .env; no committed secrets. +description: Use for pytest unit/API/mock suites, tests/cred.py, .env setup, and hygiene in contentstack-management-python. --- -# Testing — Contentstack Management Python +# Testing – Contentstack Management Python ## When to use - Adding or changing tests under **`tests/`**. - Debugging API vs mock failures; improving **`tests/cred.py`** usage. -## Runner and tooling +## Instructions + +### Runner and tooling | Suite | Path | Notes | |-------|------|--------| @@ -18,8 +20,6 @@ description: pytest—unit, API, mock; tests/cred.py and .env; no committed secr | **API** | `tests/api/**` | Live CMA — **`.env`** via **`tests/cred.py`** | | **Mock** | `tests/mock/**` | Mocked HTTP / contracts | -### Commands - | Goal | Command | |------|---------| | Unit (CI-style) | `pytest tests/unit/ -v` or `coverage run -m pytest tests/unit/` | @@ -27,18 +27,13 @@ description: pytest—unit, API, mock; tests/cred.py and .env; no committed secr | Mock | `pytest tests/mock/ -v` | | Full tree | `pytest tests/ -v` | -## Environment (`tests/cred.py`) +### Environment (tests/cred.py) - **`get_credentials()`** loads **dotenv** and returns host, tokens, and resource UIDs. - Common vars: **`HOST`**, **`APIKEY`**, **`AUTHTOKEN`**, **`MANAGEMENT_TOKEN`**, **`ORG_UID`**, plus resource UIDs as tests require. - Use a **`.env`** at repo root for local API runs; never commit secrets. -## Hygiene +### Hygiene - No committed secrets; use placeholders or env-only values for CI. - Avoid leaving **`pytest.skip`** or focused-only tests enabled in paths meant for full suite runs unless intentional. - -## References - -- **`skills/dev-workflow/SKILL.md`** -- **`skills/code-review/SKILL.md`**