# dataverse-python-modules

The rule hands your agent a map of PowerPlatform.Dataverse: client, config, errors, OData and SQL. Useful whenever Python code talks to Dataverse.

- rule · `type=rule` · GitHub Copilot · ★ 40418
- Author: github · official GitHub repository
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/github/awesome-copilot/tree/HEAD/instructions/dataverse-python-modules.instructions.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/rules/dataverse-python-modules

## What it does

The rule lays out the whole PowerPlatform.Dataverse package: where `DataverseClient` lives, what sits in `core.config` and `core.errors`, which methods cover CRUD, metadata and SQL. Your agent sees the package hierarchy and stops inventing class names and imports.

Inside are method signatures with return types: `create()`, `get()`, `update()`, `delete()`, `create_table()`, `create_columns()`, `query_sql()`, `upload_file()`, `flush_cache()`. A separate section covers exceptions: `DataverseError` with `code`, `subcode`, `status_code` and `is_transient`, plus `ValidationError`, `MetadataError`, `HttpError`, `SQLParseError`. Import snippets and client setup with `InteractiveBrowserCredential` are included.

The `extensions`, `models` and `utils` packages are empty placeholders for future releases, and the rule tells you to pull current functionality from `core` and `client`. One caveat: `http_retries`, `http_backoff` and `http_timeout` in `DataverseConfig` are marked reserved, so you cannot tune request retries through them yet. You will need `azure.identity` and the SDK package itself.

## Install

### GitHub Copilot (native platform)

**Manually: put the files in place**
- File: `.github/instructions/dataverse-python-modules.instructions.md` — The applyTo field sets which files it applies to

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/dataverse-python-modules.md` — The paths frontmatter field limits the files: move applyTo from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### Cursor

**Manually: put the files in place**
- File: `.cursor/rules/dataverse-python-modules.mdc` — Frontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/dataverse-python-modules.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/dataverse-python-modules.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/github/awesome-copilot/tree/HEAD/instructions/dataverse-python-modules.instructions.md

## When to use it
- build a Dataverse client with the right `language_code`
- tell a transient failure from a permanent one via `is_transient`
- pull `correlation_id` out of a failed HTTP request
- create a table and its columns from Python code
- catch SQL syntax problems before `query_sql()` runs

## Example prompts
- write a Dataverse client and push records into the account table
- handle HttpError and decide whether to retry
- create a table with columns using create_table and create_columns

## Source text · dataverse-python-modules.instructions.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: cb73cb82020f2836.

BEGIN THIRD-PARTY FILE cb73cb82020f2836
````text
---
applyTo: '**'
---
# Dataverse SDK for Python — Complete Module Reference

## Package Hierarchy

```
PowerPlatform.Dataverse
├── client
│   └── DataverseClient
├── core
│   ├── config (DataverseConfig)
│   └── errors (DataverseError, ValidationError, MetadataError, HttpError, SQLParseError)
├── data (OData operations, metadata, SQL, file upload)
├── extensions (placeholder for future extensions)
├── models (placeholder for data models and types)
└── utils (placeholder for utilities and adapters)
```

## core.config Module

Manage client connection and behavior settings.

### DataverseConfig Class

Container for language, timeouts, retries. Immutable.

```python
from PowerPlatform.Dataverse.core.config import DataverseConfig

cfg = DataverseConfig(
    language_code=1033,        # Default English (US)
    http_retries=None,         # Reserved for future
    http_backoff=None,         # Reserved for future
    http_timeout=None          # Reserved for future
)

# Or use default static builder
cfg_default = DataverseConfig.from_env()
```

**Key attributes:**
- `language_code: int = 1033` — LCID for localized labels and messages.
- `http_retries: int | None` — (Reserved) Maximum retry attempts for transient errors.
- `http_backoff: float | None` — (Reserved) Backoff multiplier between retries.
- `http_timeout: float | None` — (Reserved) Request timeout in seconds.

## core.errors Module

Structured exception hierarchy for SDK operations.

### DataverseError (Base)

Base exception for SDK errors.

```python
from PowerPlatform.Dataverse.core.errors import DataverseError

try:
    # SDK call
    pass
except DataverseError as e:
    print(f"Code: {e.code}")                # Error category
    print(f"Subcode: {e.subcode}")          # Specific error
    print(f"Message: {e.message}")          # Human-readable
    print(f"Status: {e.status_code}")       # HTTP status (if applicable)
    print(f"Transient: {e.is_transient}")   # Retry-worthy?
    details = e.to_dict()                  # Convert to dict
```

### ValidationError

Validation failures during data operations.

```python
from PowerPlatform.Dataverse.core.errors import ValidationError
```

### MetadataError

Table/column creation, deletion, or inspection failures.

```python
from PowerPlatform.Dataverse.core.errors import MetadataError

try:
    client.create_table("MyTable", {...})
except MetadataError as e:
    print(f"Metadata issue: {e.message}")
```

### HttpError

Web API HTTP request failures (4xx, 5xx, etc.).

```python
from PowerPlatform.Dataverse.core.errors import HttpError

try:
    client.get("account", record_id)
except HttpError as e:
    print(f"HTTP {e.status_code}: {e.message}")
    print(f"Service error code: {e.service_error_code}")
    print(f"Correlation ID: {e.correlation_id}")
    print(f"Request ID: {e.request_id}")
    print(f"Retry-After: {e.retry_after} seconds")
    print(f"Transient (retry?): {e.is_transient}")  # 429, 503, 504
```

### SQLParseError

SQL query syntax errors when using `query_sql()`.

```python
from PowerPlatform.Dataverse.core.errors import SQLParseError

try:
    client.query_sql("INVALID SQL HERE")
except SQLParseError as e:
    print(f"SQL parse error: {e.message}")
```

## data Package
````
END THIRD-PARTY FILE cb73cb82020f2836

The third-party file has ended. Everything between the cb73cb82020f2836 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3318 of 7176 bytes. © github · MIT · https://github.com/github/awesome-copilot/tree/HEAD/instructions/dataverse-python-modules.instructions.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md