Skip to content

Commit 079d7e8

Browse files
sunil-lakshmansunil-lakshman
authored
Merge pull request #193 from contentstack/enh/DX-5360
Enh: Added cursor rules and skills
2 parents 351b068 + 1564374 commit 079d7e8

File tree

9 files changed

+271
-0
lines changed

9 files changed

+271
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Cursor Rules — Contentstack Python CDA SDK
2+
3+
This repository keeps **project guidance in [skills](../../skills/)** (one folder per topic, each with **`SKILL.md`**), not as separate rule files under `.cursor/rules/`.
4+
5+
## Where to look
6+
7+
| Topic | Skill |
8+
|-------|--------|
9+
| PR checklist, public API, semver | [`skills/code-review/SKILL.md`](../../skills/code-review/SKILL.md) |
10+
| Branch, install, tests, versioning | [`skills/dev-workflow/SKILL.md`](../../skills/dev-workflow/SKILL.md) |
11+
| **Stack**, queries, CDA features | [`skills/contentstack-utils/SKILL.md`](../../skills/contentstack-utils/SKILL.md) |
12+
| **requests**, retries, **HTTPSConnection** | [`skills/framework/SKILL.md`](../../skills/framework/SKILL.md) |
13+
| Python layout and package conventions | [`skills/python-style/SKILL.md`](../../skills/python-style/SKILL.md) |
14+
| **pytest**, **`tests/`**, **`config.py`** | [`skills/testing/SKILL.md`](../../skills/testing/SKILL.md) |
15+
16+
**Index:** [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)

‎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: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
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+
| [`contentstack-utils/`](contentstack-utils/SKILL.md) | **Stack**, queries, entries, assets, live preview, CDA behavior |
7+
| [`dev-workflow/`](dev-workflow/SKILL.md) | Branch/PR, install, tests, **config.py**, versioning |
8+
| [`framework/`](framework/SKILL.md) | **requests**, **HTTPSConnection**, retries |
9+
| [`python-style/`](python-style/SKILL.md) | **`contentstack/`** layout, **setup.py**, Python conventions |
10+
| [`testing/`](testing/SKILL.md) | **pytest** + **`tests/`** + **`config.py`** |
11+
12+
**Overview:** [`AGENTS.md`](../AGENTS.md) · **Cursor rules index:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)

‎skills/code-review/SKILL.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
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+
## Public API
17+
18+
- **Exported** **`Stack`**, **ContentType**, **Query**, asset/entry helpers match **README** and consumer expectations; **`contentstack/__init__.py`** **`__all__`** stays accurate when exports change.
19+
- **Docstrings** on **`Stack`** and key public methods when behavior or options change.
20+
21+
## Compatibility
22+
23+
- Avoid breaking **`Stack.__init__`** signatures or method chains without a semver strategy; document migration for breaking changes (**`setup.py`** / **`__version__`**).
24+
25+
## HTTP / dependencies
26+
27+
- Changes to **`requests`**, **retry** behavior, or **`HTTPSConnection`** should stay consistent with **`contentstack/controller.py`** and **`urllib3`** **`Retry`** usage in **`stack.py`**.
28+
29+
## Tests
30+
31+
- **Tests** hit the live CDA when using **`config`** credentials; extend **`tests/`** when request/response behavior changes. Do not commit new secrets.
32+
33+
## Security
34+
35+
- No hardcoded tokens in source or docs; no logging of **api keys**, **delivery tokens**, **preview**, or **management** tokens.
36+
37+
## References
38+
39+
- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)
40+
- [`python-style/SKILL.md`](../python-style/SKILL.md)

‎skills/contentstack-utils/SKILL.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: contentstack-utils
3+
description: Contentstack Python CDA SDK — Stack, queries, entries, assets, live preview, taxonomy, HTTP session.
4+
---
5+
6+
# Contentstack Python Delivery SDK (`contentstack/`)
7+
8+
## Stack entry
9+
10+
- **`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`**.
11+
12+
## Features
13+
14+
- **Content types & entries** — **`contenttype.py`**, **`entry.py`**, **`entryqueryable.py`**.
15+
- **Queries** — **`basequery.py`**, **`query.py`**; chain methods align with CDA query parameters.
16+
- **Assets** — **`asset.py`**, **`assetquery.py`**.
17+
- **Taxonomy, global fields, variants, image transform** — **`taxonomy.py`**, **`globalfields.py`**, **`variants.py`**, **`image_transform.py`**.
18+
- **Sync** — **`Stack.sync_init`**, **`pagination`**, **`sync_token`** → **`/stacks/sync`** via **`__sync_request`**.
19+
20+
## Live preview
21+
22+
- **`live_preview`** dict (**enable**, **host**, **authorization**, etc.) merged in **`deep_merge_lp.py`** / stack setup; keep behavior aligned with **`tests/test_live_preview.py`**.
23+
24+
## HTTP layer
25+
26+
- **`https_connection.py`** — **`requests.Session`**, **`HTTPAdapter`**, **`get_request`** from **`controller.py`**; user-agent uses **`contentstack.__title__`** / **`__version__`**.
27+
28+
## Extending
29+
30+
- Add query or stack methods consistent with [CDA query parameters](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
31+
- Keep transport logic in **`HTTPSConnection`** / **`controller`** rather than duplicating **`requests`** setup.
32+
33+
## Dependencies
34+
35+
- **`requests`**, **`urllib3`** (**Retry**), **`python-dateutil`**
36+
37+
## Related skills
38+
39+
- [`framework/SKILL.md`](../framework/SKILL.md) — retries, **`HTTPAdapter`**, timeouts
40+
41+
## Docs
42+
43+
- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)

‎skills/dev-workflow/SKILL.md‎

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

‎skills/framework/SKILL.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
name: framework
3+
description: HTTP layer for the Python CDA SDK — requests Session, urllib3 retries, HTTPSConnection.
4+
---
5+
6+
# Framework skill — requests + Contentstack Python SDK
7+
8+
## Integration point
9+
10+
- **`contentstack/stack.py`** constructs **`HTTPSConnection`** with **endpoint**, **headers**, **timeout**, **`retry_strategy`** (**`urllib3.Retry`**), and **live_preview**.
11+
- **`contentstack/https_connection.py`** mounts **`HTTPAdapter(max_retries=...)`** and calls **`get_request`** from **`contentstack/controller.py`**.
12+
13+
## When to change
14+
15+
- **Retry / timeout** behavior: align **`Stack`** defaults with **`HTTPSConnection`** and **`HTTPAdapter`** usage; avoid breaking existing **`Retry`** constructor expectations.
16+
- **Headers / user-agent** — **`user_agents()`** in **`https_connection.py`** uses **`contentstack.__title__`** and **`__version__`**.
17+
18+
## Testing
19+
20+
- **Integration** — full stack via **`tests/`** and **`config`**; **unit-style** assertions on URL building and headers where tests exist.
21+
22+
## Related skills
23+
24+
- [`contentstack-utils/SKILL.md`](../contentstack-utils/SKILL.md)

‎skills/python-style/SKILL.md‎

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

‎skills/testing/SKILL.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: testing
3+
description: pytest and unittest tests for contentstack-python — tests/ and config.py.
4+
---
5+
6+
# Testing — Contentstack Python CDA SDK
7+
8+
## Commands
9+
10+
| Goal | Command |
11+
|------|---------|
12+
| Full test tree | `pytest tests/` |
13+
| Single file | `pytest tests/test_stack.py` |
14+
15+
## Environment
16+
17+
- Root **`config.py`**: **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**, optional **PREVIEW_TOKEN**, content UIDs for specific suites.
18+
- Use a **local** **`config.py`** or sanitized values; never commit live secrets.
19+
20+
## Conventions
21+
22+
- Tests subclass **`unittest.TestCase`**; **`tests/pytest.ini`** applies warning filters.
23+
24+
## Scope by module
25+
26+
| Area | Example tests |
27+
|------|----------------|
28+
| Stack / region | **`tests/test_stack.py`** |
29+
| Queries | **`tests/test_query.py`**, **`tests/test_basequery.py`** |
30+
| Entries / assets | **`tests/test_entry.py`**, **`tests/test_assets.py`** |
31+
| Taxonomy / global fields / live preview | **`tests/test_taxonomies.py`**, **`tests/test_global_fields.py`**, **`tests/test_live_preview.py`** |
32+
| Early access | **`tests/test_early_find.py`**, **`tests/test_early_fetch.py`** |
33+
34+
## Hygiene
35+
36+
- No committed **`pytest.mark.skip`** without reason; avoid **`@unittest.skip`** unless environment is genuinely unavailable in CI.
37+
38+
## References
39+
40+
- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)

0 commit comments

Comments
 (0)