python.mdc

# (C) 2025 GoodData Corporation
---
description: Python development - mypy-clean code patterns and typing
alwaysApply: false
---

# Python Development Guidelines

**Goal:** Ship mypy-clean code on first pass. No "write → validate → fix" loops.

**Supported versions**: Python 3.10 and higher

## Imports

**Use absolute imports only.** Relative imports break IDE navigation.
```python
from gooddata_sdk.client import GoodDataSdk  # ✅
from .client import GoodDataSdk               # ❌
```

**All imports must be at the top of the file.** Never import modules inside functions or in the middle of code. All `import` and `from ... import` statements must be placed at the top of the file, after the module docstring and `from __future__ import annotations` if present.

## Type-first habits
- Every def + local (esp empty list/dict/set) annotated; dataclasses fully typed.
- Use `from __future__ import annotations` for forward references.
- Helpers when default mutable needed:
  ```python
  def _new_set() -> set[str]:
      return set()
  ```

## External data (YAML/JSON/etc.)
- Treat loader output as `Any`; guard then normalize keys:
  ```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()}
  ```
- Narrow collections once: `entries = [x for x in cast(list[object], cfg.get("items", [])) if isinstance(x, str)]`.
- Prefer `TypedDict`/dataclass when schema known.

## Logging & diagnostics
- Never log raw `Any`; cast or pre-format (`logger.warning("… %r", safe)`).
- Avoid redundant `isinstance` after data narrowed; mypy flags it.

## Casts / guards
- Single authoritative `cast(...)` + reuse variable.
- Guard pattern: `if isinstance(mode_raw, str): mode = mode_raw else: raise ValueError("mode str")`.
- `typing.assert_never` for exhaustive branches.

## Documentation

**Google-style docstrings** for all public APIs.

## Dependencies

Required: general/general
Related: technologies/testing, packages/*