{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"dataverse-python-modules","version":"0.1.0"},"spec":{"agents_md":"---\napplyTo: '**'\n---\n# Dataverse SDK for Python — Complete Module Reference\n\n## Package Hierarchy\n\n```\nPowerPlatform.Dataverse\n├── client\n│   └── DataverseClient\n├── core\n│   ├── config (DataverseConfig)\n│   └── errors (DataverseError, ValidationError, MetadataError, HttpError, SQLParseError)\n├── data (OData operations, metadata, SQL, file upload)\n├── extensions (placeholder for future extensions)\n├── models (placeholder for data models and types)\n└── utils (placeholder for utilities and adapters)\n```\n\n## core.config Module\n\nManage client connection and behavior settings.\n\n### DataverseConfig Class\n\nContainer for language, timeouts, retries. Immutable.\n\n```python\nfrom PowerPlatform.Dataverse.core.config import DataverseConfig\n\ncfg = DataverseConfig(\n    language_code=1033,        # Default English (US)\n    http_retries=None,         # Reserved for future\n    http_backoff=None,         # Reserved for future\n    http_timeout=None          # Reserved for future\n)\n\n# Or use default static builder\ncfg_default = DataverseConfig.from_env()\n```\n\n**Key attributes:**\n- `language_code: int = 1033` — LCID for localized labels and messages.\n- `http_retries: int | None` — (Reserved) Maximum retry attempts for transient errors.\n- `http_backoff: float | None` — (Reserved) Backoff multiplier between retries.\n- `http_timeout: float | None` — (Reserved) Request timeout in seconds.\n\n## core.errors Module\n\nStructured exception hierarchy for SDK operations.\n\n### DataverseError (Base)\n\nBase exception for SDK errors.\n\n```python\nfrom PowerPlatform.Dataverse.core.errors import DataverseError\n\ntry:\n    # SDK call\n    pass\nexcept DataverseError as e:\n    print(f\"Code: {e.code}\")                # Error category\n    print(f\"Subcode: {e.subcode}\")          # Specific error\n    print(f\"Message: {e.message}\")          # Human-readable\n    print(f\"Status: {e.status_code}\")       # HTTP status (if applicable)\n    print(f\"Transient: {e.is_transient}\")   # Retry-worthy?\n    details = e.to_dict()                  # Convert to dict\n```\n\n### ValidationError\n\nValidation failures during data operations.\n\n```python\nfrom PowerPlatform.Dataverse.core.errors import ValidationError\n```\n\n### MetadataError\n\nTable/column creation, deletion, or inspection failures.\n\n```python\nfrom PowerPlatform.Dataverse.core.errors import MetadataError\n\ntry:\n    client.create_table(\"MyTable\", {...})\nexcept MetadataError as e:\n    print(f\"Metadata issue: {e.message}\")\n```\n\n### HttpError\n\nWeb API HTTP request failures (4xx, 5xx, etc.).\n\n```python\nfrom PowerPlatform.Dataverse.core.errors import HttpError\n\ntry:\n    client.get(\"account\", record_id)\nexcept HttpError as e:\n    print(f\"HTTP {e.status_code}: {e.message}\")\n    print(f\"Service error code: {e.service_error_code}\")\n    print(f\"Correlation ID: {e.correlation_id}\")\n    print(f\"Request ID: {e.request_id}\")\n    print(f\"Retry-After: {e.retry_after} seconds\")\n    print(f\"Transient (retry?): {e.is_transient}\")  # 429, 503, 504\n```\n\n### SQLParseError\n\nSQL query syntax errors when using `query_sql()`.\n\n```python\nfrom PowerPlatform.Dataverse.core.errors import SQLParseError\n\ntry:\n    client.query_sql(\"INVALID SQL HERE\")\nexcept SQLParseError as e:\n    print(f\"SQL parse error: {e.message}\")\n```\n\n## data Package\n\nLow-level OData protocol, metadata, SQL, and file operations (internal delegation).\n\nThe `data` package is primarily internal; the high-level `DataverseClient` in the `client` module wraps and exposes:\n- CRUD operations via OData\n- Metadata management (create/update/delete tables and columns)\n- SQL query execution\n- File upload handling\n\nUsers interact with these via `DataverseClient` methods (e.g., `create()`, `get()`, `update()`, `delete()`, `create_table()`, `query_sql()`, `upload_file()`).\n\n## extensions Package (Placeholder)\n\nReserved for future extension points (e.g., custom adapters, middleware).\n\nCurrently empty; use core and client modules for current functionality.\n\n## models Package (Placeholder)\n\nReserved for future data model definitions and type definitions.\n\nCurrently empty. Data structures return as `dict` (OData) and are JSON-serializable.\n\n## utils Package (Placeholder)\n\nReserved for utility adapters and helpers.\n\nCurrently empty. Helper functions may be added in future releases.\n\n## client Module\n\nMain user-facing API.\n\n### DataverseClient Class\n\nHigh-level client for all Dataverse operations.\n\n```python\nfrom azure.identity import InteractiveBrowserCredential\nfrom PowerPlatform.Dataverse.client import DataverseClient\nfrom PowerPlatform.Dataverse.core.config import DataverseConfig\n\n# Create credential\ncredential = InteractiveBrowserCredential()\n\n# Optionally configure\ncfg = DataverseConfig(language_code=1033)\n\n# Create client\nclient = DataverseClient(\n    base_url=\"https://org.crm.dynamics.com\",\n    credential=credential,\n    config=cfg  # optional\n)\n```\n\n#### CRUD Methods\n\n- `create(table_schema_name, records)` → `list[str]` — Create records, return GUIDs.\n- `get(table_schema_name, record_id=None, select, filter, orderby, top, expand, page_size)` → Record(s).\n- `update(table_schema_name, ids, changes)` → `None` — Update records.\n- `delete(table_schema_name, ids, use_bulk_delete=True)` → `str | None` — Delete records.\n\n#### Metadata Methods\n\n- `create_table(table_schema_name, columns, solution_unique_name, primary_column_schema_name)` → Metadata dict.\n- `create_columns(table_schema_name, columns)` → `list[str]`.\n- `delete_columns(table_schema_name, columns)` → `list[str]`.\n- `delete_table(table_schema_name)` → `None`.\n- `get_table_info(table_schema_name)` → Metadata dict or `None`.\n- `list_tables()` → `list[str]`.\n\n#### SQL \u0026 Utilities\n\n- `query_sql(sql)` → `list[dict]` — Execute read-only SQL.\n- `upload_file(table_schema_name, record_id, file_name_attribute, path, mode, mime_type, if_none_match)` → `None` — Upload to file column.\n- `flush_cache(kind)` → `int` — Clear SDK caches (e.g., `\"picklist\"`).\n\n## Imports Summary\n\n```python\n# Main client\nfrom PowerPlatform.Dataverse.client import DataverseClient\n\n# Configuration\nfrom PowerPlatform.Dataverse.core.config import DataverseConfig\n\n# Errors\nfrom PowerPlatform.Dataverse.core.errors import (\n    DataverseError,\n    ValidationError,\n    MetadataError,\n    HttpError,\n    SQLParseError,\n)\n```\n\n## References\n\n- Module docs: https://learn.microsoft.com/en-us/python/api/powerplatform-dataverse-client/\n- Core: https://learn.microsoft.com/en-us/python/api/powerplatform-dataverse-client/powerplatform.dataverse.core\n- Data: https://learn.microsoft.com/en-us/python/api/powerplatform-dataverse-client/powerplatform.dataverse.data\n- Extensions: https://learn.microsoft.com/en-us/python/api/powerplatform-dataverse-client/powerplatform.dataverse.extensions\n- Models: https://learn.microsoft.com/en-us/python/api/powerplatform-dataverse-client/powerplatform.dataverse.models\n- Utils: https://learn.microsoft.com/en-us/python/api/powerplatform-dataverse-client/powerplatform.dataverse.utils\n- Client: https://learn.microsoft.com/en-us/python/api/powerplatform-dataverse-client/powerplatform.dataverse.client\n","description":"`","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/dataverse-python-modules.instructions.md"},"manifest":{}},"content_hash":[136,172,131,103,175,207,96,255,51,237,102,112,128,96,169,231,130,27,107,134,27,137,16,95,147,64,174,128,211,229,36,116],"trust_level":"unsigned","yanked":false}