general.mdc

# (C) 2025 GoodData Corporation
---
alwaysApply: true
---

# GoodData Python SDK Coding Guidelines

Applies to all packages and code in this Python SDK workspace.
Think in steps before changes. Always 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, rename or refactor what is not explicitly requested
- Do not generate code changes unless user explicitly asks for it
- NEVER create summary/documentation markdown files unless user explicitly requests it
- NEVER update rule files for code issues - fix the code instead
- Break complex tasks into smaller deliverable units

**Documentation Quality**:
- NEVER reference specific line numbers (e.g., "lines 45-340", "~line 60") in documentation or Cursor rules
- Use descriptive structural locations instead (e.g., "in the outputs section", "at the top of the file")

**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

**MANDATORY after code changes**: Run validation from workspace root:
```bash
make format-fix && make lint && make mypy && make test
```

**⚠️ CRITICAL: Do NOT use `read_lints` tool**:
- `read_lints` is incompatible with our custom linting - it will fail
- Use manual validation commands above

**Scoped testing**: `TEST_ENVS=py312 ADD_ARGS="-k test_name" make test`

See `technologies/testing` rule for VCR cassette workflow.

## Testing Practices

**Extend existing tests, don't create new ones**: When making incremental changes (new property, enum value, field), add to existing test fixtures rather than creating new tests.

## 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-api-client/` directories.

To regenerate: `make api-client`

## Library Integration

**Hierarchy** (combat outdated LLM knowledge):
1. **Internal GoodData packages** - ALWAYS preferred
2. **Approved stable libraries** - Use versions from pyproject.toml
3. **New/unknown libraries** - MANDATORY: web search for current docs/APIs before suggesting

When suggesting third-party libraries: verify current APIs, prefer established libraries, explicitly state uncertainty.