Skip to content

Commit 59137f5

Browse files
sunil-lakshmansunil-lakshman
committed
Enh: Added cursor rules and skills
1 parent fc32567 commit 59137f5

File tree

12 files changed

+341
-0
lines changed

12 files changed

+341
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Cursor Rules — Contentstack Python CDA SDK
2+
3+
Rules for **contentstack-python**: Python **Content Delivery API (CDA)** SDK (`pip` package **Contentstack**).
4+
5+
## Rules overview
6+
7+
| Rule | Role |
8+
|------|------|
9+
| [`dev-workflow.md`](dev-workflow.md) | Branch/PR, install, tests |
10+
| [`python.mdc`](python.mdc) | Python layout, `contentstack/`, `setup.py` |
11+
| [`contentstack-delivery-python.mdc`](contentstack-delivery-python.mdc) | **Stack**, queries, live preview, **HTTPSConnection** / **requests** |
12+
| [`testing.mdc`](testing.mdc) | **pytest** + **unittest** under `tests/` |
13+
| [`code-review.mdc`](code-review.mdc) | PR checklist (**always applied**) |
14+
15+
## Rule application
16+
17+
| Context | Typical rules |
18+
|---------|----------------|
19+
| **Every session** | `code-review.mdc` |
20+
| **Most files** | `dev-workflow.md` |
21+
| **`contentstack/`** | `python.mdc` + `contentstack-delivery-python.mdc` |
22+
| **`tests/**`** | `testing.mdc` |
23+
| **Packaging** | `python.mdc` |
24+
25+
## Quick reference
26+
27+
| File | `alwaysApply` | Globs (summary) |
28+
|------|---------------|-----------------|
29+
| `dev-workflow.md` | no | `**/*.py`, `requirements.txt`, `setup.py`, `tests/pytest.ini` |
30+
| `python.mdc` | no | `contentstack/**/*.py`, `setup.py` |
31+
| `contentstack-delivery-python.mdc` | no | `contentstack/**/*.py` |
32+
| `testing.mdc` | no | `tests/**/*.py`, `tests/pytest.ini` |
33+
| `code-review.mdc` | **yes** | — |
34+
35+
## Skills
36+
37+
- [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)

‎.cursor/rules/code-review.mdc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
description: "PR checklist for Contentstack Python CDA SDK — API, Stack, HTTP layer, tests"
3+
alwaysApply: true
4+
---
5+
6+
# Code review — Contentstack Python CDA SDK
7+
8+
## Public API
9+
10+
- **Exported** **`Stack`**, **ContentType**, **Query**, asset/entry helpers match **README** and consumer expectations; **`contentstack/__init__.py`** **`__all__`** stays accurate when exports change.
11+
- **Docstrings** on **`Stack`** and key public methods when behavior or options change.
12+
13+
## Compatibility
14+
15+
- Avoid breaking **`Stack.__init__`** signatures or method chains without a semver strategy; document migration for breaking changes (**`setup.py`** / **`__version__`**).
16+
17+
## HTTP / dependencies
18+
19+
- Changes to **`requests`**, **retry** behavior, or **`HTTPSConnection`** should stay consistent with **`contentstack/controller.py`** and **`urllib3`** **`Retry`** usage in **`stack.py`**.
20+
21+
## Tests
22+
23+
- **Tests** hit the live CDA when using **`config`** credentials; extend **`tests/`** when request/response behavior changes. Do not commit new secrets.
24+
25+
## Security
26+
27+
- No hardcoded tokens in source or docs; no logging of **api keys**, **delivery tokens**, **preview**, or **management** tokens.

‎.cursor/rules/contentstack-delivery-python.mdc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
description: "CDA Delivery SDK — Stack, queries, live preview, requests session"
3+
globs: ["contentstack/**/*.py"]
4+
alwaysApply: false
5+
---
6+
7+
# Contentstack Python Delivery SDK (`contentstack/`)
8+
9+
## Stack entry
10+
11+
- **`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`**.
12+
13+
## Features
14+
15+
- **Content types & entries** — **`contenttype.py`**, **`entry.py`**, **`entryqueryable.py`**.
16+
- **Queries** — **`basequery.py`**, **`query.py`**; chain methods align with CDA query parameters.
17+
- **Assets** — **`asset.py`**, **`assetquery.py`**.
18+
- **Taxonomy, global fields, variants, image transform** — **`taxonomy.py`**, **`globalfields.py`**, **`variants.py`**, **`image_transform.py`**.
19+
- **Sync** — **`Stack.sync_init`**, **`pagination`**, **`sync_token`** → **`/stacks/sync`** via **`__sync_request`**.
20+
21+
## Live preview
22+
23+
- **`live_preview`** dict (**enable**, **host**, **authorization**, etc.) merged in **`deep_merge_lp.py`** / stack setup; keep behavior aligned with **`tests/test_live_preview.py`**.
24+
25+
## HTTP layer
26+
27+
- **`https_connection.py`** — **`requests.Session`**, **`HTTPAdapter`**, **`get_request`** from **`controller.py`**; user-agent uses **`contentstack.__title__`** / **`__version__`**.
28+
29+
## Docs
30+
31+
- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)

‎.cursor/rules/dev-workflow.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
description: "Branches, install, and tests for contentstack-python"
3+
globs: ["**/*.py", "requirements.txt", "setup.py", "tests/pytest.ini"]
4+
alwaysApply: false
5+
---
6+
7+
# Development workflow — Contentstack Python CDA SDK
8+
9+
## Before a PR
10+
11+
1. **Install** — `pip install -r requirements.txt` and editable package as needed: `pip install -e .`
12+
2. **Tests** — `pytest tests/` (or `python -m pytest tests/`) from the repo root; **`tests/pytest.ini`** applies.
13+
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.
14+
15+
## Versioning
16+
17+
- Bump **`contentstack/__init__.py`** **`__version__`** and **`setup.py`**-driven releases per semver for user-visible SDK changes.
18+
19+
## Links
20+
21+
- [`AGENTS.md`](../../AGENTS.md) · [`skills/contentstack-delivery-python/SKILL.md`](../../skills/contentstack-delivery-python/SKILL.md)

‎.cursor/rules/python.mdc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: "Python conventions for the CDA SDK package and packaging"
3+
globs:
4+
- "contentstack/**/*.py"
5+
- "setup.py"
6+
alwaysApply: false
7+
---
8+
9+
# Python — Contentstack CDA SDK
10+
11+
## Layout
12+
13+
- **`contentstack/stack.py`** — **`Stack`**, **`ContentstackRegion`**.
14+
- **`contentstack/query.py`**, **`basequery.py`** — query building.
15+
- **`contentstack/entry.py`**, **`asset.py`**, **`contenttype.py`**, **`taxonomy.py`**, **`globalfields.py`** — domain objects.
16+
- **`contentstack/https_connection.py`**, **`controller.py`** — HTTP.
17+
- **`contentstack/error_messages.py`**, **`utility.py`** — shared helpers.
18+
19+
## Style
20+
21+
- Match existing patterns (typing on **`Stack`**, **unittest**-style tests in **`tests/`**).
22+
- Prefer clear public APIs over internal churn; keep module boundaries similar to neighboring files.
23+
24+
## Dependencies
25+
26+
- **`requests`**, **`python-dateutil`**, **`urllib3`** (Retry) — see **`setup.py`** **`install_requires`**.
27+
28+
## Security
29+
30+
- Do not log **delivery tokens**, **preview tokens**, **api keys**, or **management** tokens; follow existing logging on **`Stack`**.

‎.cursor/rules/testing.mdc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
description: "pytest and unittest integration tests for contentstack-python"
3+
globs:
4+
- "tests/**/*.py"
5+
- "tests/pytest.ini"
6+
alwaysApply: false
7+
---
8+
9+
# Testing — Contentstack Python CDA SDK
10+
11+
## Runner
12+
13+
- **`pytest tests/`** from repo root ( **`tests/pytest.ini`** — warning filters).
14+
- Tests are **`unittest.TestCase`** subclasses; pytest discovers them normally.
15+
16+
## Credentials
17+
18+
- Most integration tests **`import config`** from the repo root **`config.py`** ( **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**, optional **PREVIEW_TOKEN**, entry UIDs, etc.).
19+
- Treat **`config.py`** as **local-only** when it contains secrets; do not commit credentials.
20+
21+
## Scope by module
22+
23+
| Area | Example tests |
24+
|------|----------------|
25+
| Stack / region | **`tests/test_stack.py`** |
26+
| Queries | **`tests/test_query.py`**, **`tests/test_basequery.py`** |
27+
| Entries / assets | **`tests/test_entry.py`**, **`tests/test_assets.py`** |
28+
| Taxonomy / global fields / live preview | **`tests/test_taxonomies.py`**, **`tests/test_global_fields.py`**, **`tests/test_live_preview.py`** |
29+
| Early access | **`tests/test_early_find.py`**, **`tests/test_early_fetch.py`** |
30+
31+
## Hygiene
32+
33+
- No committed **`pytest.mark.skip`** without reason; avoid **`@unittest.skip`** unless environment is genuinely unavailable in CI.

‎AGENTS.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# AGENTS.md — AI / automation context
2+
3+
## Project
4+
5+
| | |
6+
|---|---|
7+
| **Name** | **Contentstack** (PyPI) — **Python Content Delivery SDK** |
8+
| **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`**. |
9+
| **Repository** | [contentstack/contentstack-python](https://github.com/contentstack/contentstack-python.git) |
10+
11+
## Tech stack
12+
13+
| Area | Details |
14+
|------|---------|
15+
| **Language** | **Python** (see **`setup.py`** `python_requires`, classifiers) |
16+
| **HTTP** | **`requests`**, **`urllib3`** |
17+
| **Tests** | **pytest** + **`unittest.TestCase`** under **`tests/`** |
18+
| **Packaging** | **`setuptools`** / **`setup.py`**, package **`contentstack`** |
19+
20+
## Source layout
21+
22+
| Path | Role |
23+
|------|------|
24+
| `contentstack/stack.py` | **`Stack`**, **`ContentstackRegion`**, endpoint and **HTTPSConnection** wiring |
25+
| `contentstack/https_connection.py`, `contentstack/controller.py` | Session, retries, **`get_request`** |
26+
| `contentstack/query.py`, `contentstack/basequery.py` | Queries |
27+
| `contentstack/entry.py`, `asset.py`, `contenttype.py`, … | Domain modules |
28+
| `contentstack/__init__.py` | Public exports (**`Stack`**, **`Entry`**, **`Asset`**, …), **`__version__`** |
29+
| `config.py` (repo root) | Test credentials and UIDs — **must not commit secrets** |
30+
| `tests/*.py` | Integration-style tests importing **`config`** |
31+
32+
## Common commands
33+
34+
```bash
35+
pip install -r requirements.txt
36+
pip install -e .
37+
pytest tests/
38+
```
39+
40+
## Environment / test configuration
41+
42+
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.
43+
44+
## Further guidance
45+
46+
- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
47+
- **Skills:** [`skills/README.md`](skills/README.md)
48+
49+
Product docs: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).

‎skills/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Project skills — Contentstack Python CDA SDK
2+
3+
| Skill | When to use |
4+
|-------|-------------|
5+
| [`code-review/`](code-review/SKILL.md) | PR review, semver, public API on **Stack** |
6+
| [`testing/`](testing/SKILL.md) | **pytest** + **`tests/`** + **`config.py`** |
7+
| [`contentstack-delivery-python/`](contentstack-delivery-python/SKILL.md) | **Stack**, queries, entries, assets, live preview |
8+
| [`framework/`](framework/SKILL.md) | **requests**, **HTTPSConnection**, retries |
9+
10+
**Overview:** [`AGENTS.md`](../AGENTS.md) · **Rules:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)

‎skills/code-review/SKILL.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: code-review
3+
description: PR review for Contentstack Python CDA SDK — public API, Stack, HTTP layer, tests.
4+
---
5+
6+
# Code review — Contentstack Python CDA SDK
7+
8+
## Checklist
9+
10+
- [ ] **API:** New or changed **`Stack`** / content-type / query / entry methods documented; **`contentstack/__init__.py`** exports updated if needed.
11+
- [ ] **Version:** **`__version__`** in **`contentstack/__init__.py`** aligned with release strategy for breaking changes.
12+
- [ ] **HTTP:** **`https_connection.py`** / **`controller.py`** changes keep retry and timeout behavior predictable.
13+
- [ ] **Tests:** **`pytest tests/`** passes; extend **`tests/`** when CDA behavior changes.
14+
- [ ] **Secrets:** No tokens in repo; **`config.py`** remains local-only when it holds real credentials.
15+
16+
## References
17+
18+
- `.cursor/rules/code-review.mdc`
19+
- `.cursor/rules/dev-workflow.md`

‎skills/contentstack-delivery-python/SKILL.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: contentstack-delivery-python
3+
description: Contentstack Python CDA SDK — Stack, queries, entries, assets, live preview, taxonomy.
4+
---
5+
6+
# Contentstack Python Delivery SDK skill
7+
8+
## Entry
9+
10+
- **`contentstack.Stack(api_key, delivery_token, environment, ...)`** — **`contentstack/stack.py`**: validates credentials, sets **region** / **host**, builds **`endpoint`**, instantiates **`HTTPSConnection`** with **retry_strategy** and **live_preview**.
11+
12+
## Structure
13+
14+
- **`Stack`** — content types, entries, assets, sync helpers as implemented on the class.
15+
- **Queries** — **`BaseQuery`**, **`Query`**, **`AssetQuery`**, **`EntryQueryable`**, etc.
16+
- **Live preview** — **`live_preview`** dict and **`deep_merge_lp`** behavior.
17+
- **Sync** — **`sync_init`**, **`pagination`**, **`sync_token`** on **`Stack`**.
18+
19+
## Extending
20+
21+
- Add query or stack methods consistent with [CDA query parameters](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
22+
- Keep transport logic in **`HTTPSConnection`** / **`controller`** rather than duplicating **`requests`** setup.
23+
24+
## Dependencies
25+
26+
- **`requests`**, **`urllib3`** (**Retry**), **`python-dateutil`**
27+
28+
## Docs
29+
30+
- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
31+
32+
## Rule shortcut
33+
34+
- `.cursor/rules/contentstack-delivery-python.mdc`

0 commit comments

Comments
 (0)