Merge pull request #1248 from gooddata/snapshot-master-8c301641-to-rel/dev

[bot] Merge master/8c301641 into rel/dev

Author: yenkins-admin

.cursor/rules/cursor/rules.mdc

@@ -0,0 +1,64 @@
+---
+description: How to create or update Cursor rule files - minimal templates and standards
+alwaysApply: false
+---
+
+# Creating and Updating Cursor Rules
+
+## Folder Structure
+
+- `.cursor/rules/general/` - General rules (always applied)
+- `.cursor/rules/packages/` - Package-specific rules
+- `.cursor/rules/technologies/` - Technology rules (Python, testing)
+- `.cursor/rules/cursor/` - Cursor workflow and meta-rules
+
+## Rule Creation Process
+
+1. **Ask for clarification** if codebase location unclear
+2. **Investigate the codebase** relevant to the rule
+3. **Look at similar existing rules** as examples (better than templates)
+4. **Keep it minimal** - target 25-40 lines max
+5. **Focus on proprietary knowledge** - not generic patterns
+
+## Updating Existing Rules
+
+**CRITICAL**: Be MINIMAL. Add only what prevents actual errors.
+
+**DO (Minimal):**
+```python
+# Just the pattern that fixes the error
+from typing import TYPE_CHECKING, Any
+if TYPE_CHECKING:
+    Context = MCPContext[Any, Any, Any]
+```
+
+**DON'T (Verbose):**
+- ❌ Pattern explanations (why it works, alternatives, trade-offs)
+- ❌ Multiple examples (good vs bad, before vs after)
+- ❌ Best practices unrelated to errors
+- ❌ Prose explanations ("Why:", "Note:", paragraphs)
+- ❌ Decision matrices or tables (unless critical for error prevention)
+- ❌ Checklists (unless they prevent actual errors)
+- ❌ Step-by-step tutorials
+- ❌ Verbose "correct vs wrong" comparisons
+
+**Rule of thumb**: If it didn't cause a validation error, don't add it.
+
+**Target length**: 25-40 lines. If over 50 lines, too verbose.
+
+## Rule Structure
+
+**Essential sections:**
+- Description header (1 line)
+- Owns / Does NOT Own (clear boundaries)
+- Critical constraints (if any)
+- Dependencies
+
+## Rule Header Format
+
+```markdown
+---
+description: {Brief - used by Cursor for rule selection}
+alwaysApply: false  # (true only for general rules)
+---
+```

.cursor/rules/cursor/workflow-validation.mdc

@@ -0,0 +1,19 @@
+---
+description: Cursor IDE workflow validation and rule management
+alwaysApply: true
+---
+
+# Cursor IDE Workflow Validation
+
+## Workflow Constraints
+
+- Include all rules related to the user question; if rules mention dependencies, include those too.
+- After fully answering, report the list of used rules.
+- Example: **Used rules**: general/general, technologies/python, packages/gooddata-sdk
+- Do not print rule previews or long plans.
+- Keep status updates to one short sentence.
+- Never inline full rule contents; reference by rule path only when needed.
+
+## Rule Search
+
+Always look for relevant cursor rules based on the character of changes.

.cursor/rules/general/general.mdc

@@ -0,0 +1,70 @@
+---
+alwaysApply: true
+---
+
+# GoodData Python SDK Coding Guidelines
+
+Applies to all packages and code in this Python SDK workspace.
+Think in steps before changes. Search for relevant cursor rules based on the character of changes.
+
+## Core Principles
+
+**Search first, don't invent**: Always search this repository for everything related to the developer question. **Do not invent a new design for something that already exists!**
+
+**Code Principles**: **1** Simplicity, **2** Readability, **3** Performance (don't over-optimize), **4** Maintainability, **5** Testability, **6** Reusability, **7** Encapsulation & single responsibility
+
+## ⚠️ CRITICAL: AI Behavior Rules - ALWAYS ENFORCE
+
+**NO AUTO-IMPLEMENTATION**: 
+- Do not generate code changes unless user explicitly asks for it
+- NEVER create summary/documentation markdown files unless explicitly requested
+- Break complex tasks into smaller deliverable units
+
+**For complex tasks**:
+1. Implement ONLY the first task, then STOP
+2. Ask permission to continue, offering: (a) next task only, or (b) all remaining tasks
+3. Create todos but DO NOT auto-implement them
+4. When in doubt, ask before implementing
+
+## Code Validation
+
+**If gdc-ruler MCP server is available**: Use `validate_python` tool with this workspace path.
+```
+validate_python(path=".")  # From workspace root
+```
+
+**Otherwise**: Run manually:
+```bash
+make format-fix && make mypy && make test
+```
+
+**Scoped testing**: `TEST_ENVS=py312 ADD_ARGS="-k test_name" make test`
+
+See `technologies/testing` rule for VCR cassette workflow.
+
+## Package Structure
+
+**Workspace packages** (in `packages/`):
+- `gooddata-sdk` - Core SDK for GoodData Cloud
+- `gooddata-pandas` - Pandas integration layer
+- `gooddata-dbt`, `gooddata-flight-server`, `gooddata-flexconnect`, `gooddata-pipelines`
+- `tests-support` - Shared test utilities
+
+**Generated clients** (do NOT edit manually):
+- `gooddata-api-client` - Generated from OpenAPI specs
+
+## Dependencies
+
+**Internal**: Use `~={current_version}` for package dependencies.
+
+**Adding**: Add to `pyproject.toml`, run `uv lock`.
+
+## OpenAPI Client Generation
+
+**DO NOT manually edit** generated client code in `gooddata-*-client/` directories.
+
+See `.openapi-generator/README.md` for regeneration instructions.
+
+## Fast-Changing Dependencies
+
+**When suggesting third-party libraries**: Verify current APIs, prefer established libraries, check Python 3.10+ compatibility.

.cursor/rules/packages/gooddata-pandas.mdc

@@ -0,0 +1,37 @@
+---
+description: GoodData Pandas package - pandas integration layer for GoodData SDK
+alwaysApply: false
+---
+
+# GoodData Pandas Package
+
+**Location**: `packages/gooddata-pandas/`
+
+## Owns
+
+- Pandas Series and DataFrame creation from GoodData data
+- Integration layer between GoodData SDK and pandas
+
+## Does NOT Own
+
+- Core SDK functionality → gooddata-sdk package
+
+## Architecture
+
+**Dependency**: Depends on `gooddata-sdk` core package.
+
+**Main class**: `GoodPandas` - extends SDK with pandas-specific operations
+
+## Usage
+
+```python
+from gooddata_pandas import GoodPandas
+
+gp = GoodPandas(host="https://example.gooddata.com", token="...")
+df = gp.data_frames(workspace_id="demo", insight_id="...")
+```
+
+## Dependencies
+
+Required: technologies/python, packages/gooddata-sdk
+Related: technologies/testing

.cursor/rules/packages/gooddata-sdk.mdc

@@ -0,0 +1,48 @@
+---
+description: GoodData SDK core package - primary interface for GoodData Cloud
+alwaysApply: false
+---
+
+# GoodData SDK Package
+
+**Location**: `packages/gooddata-sdk/`
+
+## Owns
+
+- Core SDK client (`GoodDataSdk`) - main entry point
+- Catalog services (workspaces, data sources, users, permissions)
+- Compute services (execution, caching, export)
+- Visualization services (insights, dashboards)
+- Declarative API support (layout export/import)
+- Model management (LDM, PDM operations)
+
+## Does NOT Own
+
+- Pandas integration → gooddata-pandas package
+- dbt integration → gooddata-dbt package
+- Flight server → gooddata-flight-server package
+- API client generation → gooddata-api-client (generated)
+
+## Architecture
+
+**Service-based**: `catalog_*`, `compute_*`, `insights_*`, `tables_*`
+
+**Depends on**: `gooddata-api-client` (generated OpenAPI client)
+
+## SDK Usage
+
+```python
+from gooddata_sdk import GoodDataSdk
+
+sdk = GoodDataSdk.create(host="https://example.gooddata.com", token="...")
+workspaces = sdk.catalog_workspace.list_workspaces()
+```
+
+## Testing
+
+Uses vcrpy cassettes. See `technologies/testing` rule for workflow.
+
+## Dependencies
+
+Required: technologies/python, technologies/testing
+Related: packages/gooddata-pandas

.cursor/rules/technologies/python.mdc

@@ -0,0 +1,54 @@
+---
+description: Python development - mypy-clean code patterns
+alwaysApply: false
+---
+
+# Python Development
+
+**Goal:** Ship mypy-clean code on first pass. No "write → validate → fix" loops.
+
+**Supported versions**: Python 3.10 and higher
+
+## Imports
+
+**Absolute imports only.** Relative imports break monorepo navigation.
+```python
+from gooddata_sdk.client import GoodDataSdk  # ✅
+from .client import GoodDataSdk               # ❌
+```
+
+**All imports at top of file.** After docstring and `from __future__ import annotations`.
+
+## Type-first Habits
+
+- Every def + local (esp empty list/dict/set) annotated; dataclasses fully typed.
+- Use `from __future__ import annotations` for forward references.
+- Guard external data (YAML/JSON) as `Any` then narrow types.
+
+## External Data (YAML/JSON)
+
+```python
+raw = yaml.safe_load(handle)
+if not isinstance(raw, dict):
+    raise ValueError("expected mapping")
+cfg: dict[str, object] = {str(k): v for k, v in raw.items()}
+```
+
+## Casts / Guards
+
+- Single authoritative `cast(...)` + reuse variable
+- Guard pattern: `if isinstance(mode_raw, str): mode = mode_raw else: raise ValueError("...")`
+- `typing.assert_never` for exhaustive branches
+
+## Validation flow (If MCP server installed)
+- Python-only chores: `validate_python(path)` (format, lint, types, test).
+- Mixed stacks: run Python + Kotlin validators separately; skip umbrella `validate` until new classifier routing lands.
+
+## Documentation
+
+**Google-style docstrings** for all public APIs.
+
+## Dependencies
+
+Required: general/general
+Related: technologies/testing, packages/*

.cursor/rules/technologies/testing.mdc

@@ -0,0 +1,58 @@
+---
+description: Validation and testing - VCR cassettes for HTTP snapshots
+alwaysApply: false
+---
+
+# Validation & Testing
+
+## Validation Flow
+
+**If gdc-ruler MCP server is available**:
+```
+validate_python(path=".")                    # Full validation
+validate_python(path=".", steps=["format", "lint"])  # Quick check
+```
+
+**Manual commands** (from workspace root):
+```bash
+make format-fix  # ruff format + fix
+make mypy        # Type check (aliased as `make types`)
+make test        # pytest via tox (all Python versions)
+```
+
+**Scoped**:
+```bash
+TEST_ENVS=py312,py313 make test           # Specific Python versions
+ADD_ARGS="-k test_catalog" make test      # Filter tests
+RECREATE_ENVS=1 make test                 # Force tox rebuild
+```
+
+**CI-like**: `make test-ci` (Docker-based)
+
+## VCR Cassettes (HTTP Snapshots)
+
+**Purpose**: Record GoodData Cloud HTTP calls for reproducible tests.
+
+**Update workflow** (when API changes):
+```bash
+docker-compose up          # Start local GoodData Cloud
+make remove-cassettes      # Delete old fixtures
+make test                  # Generates new cassettes
+git add tests/**/fixtures/*.yaml
+```
+
+**Location**: `tests/**/fixtures/*.yaml`
+
+## Test Pattern
+
+```python
+@vcr.use_cassette("tests/catalog/fixtures/test_workspace.yaml")
+def test_get_workspace(sdk):
+    workspace = sdk.catalog_workspace.get_workspace("demo")
+    assert workspace.id == "demo"
+```
+
+## Dependencies
+
+Required: technologies/python
+Related: general/general

Makefile

@@ -70,9 +70,12 @@ download:
 .PHONY: mypy
 mypy:
 	RESULT=0; \
-	for project in $(NO_CLIENT_GD_PROJECTS_DIRS); do $(MAKE) -C packages/$${project} $@ || RESULT=$$?; done; \
+	for project in $(NO_CLIENT_GD_PROJECTS_DIRS); do $(MAKE) -C packages/$${project} mypy || RESULT=$$?; done; \
 	exit $$RESULT
 
+.PHONY: types
+types: mypy
+
 .PHONY: test
 test:
 	RESULT=0; \

project_common.mk

@@ -40,6 +40,9 @@ format-fix:
 mypy:
 	uv run tox $(TOX_FLAGS) -e mypy
 
+.PHONY: types
+types: mypy
+
 .PHONY: test
 test:
 	uv run tox -v $(TOX_FLAGS) $(LOCAL_TEST_ENVS) $(LOCAL_ADD_ARGS)