This pull request significantly improves the documentation for the Dataverse Python SDK, focusing on clearer authentication setup, improved async usage guidance, enhanced exception handling documentation, and more accurate and idiomatic code examples. The changes help new and existing users better understand both basic and advanced SDK usage, error handling, and recommended best practices.

Authentication and credential setup:

• Expanded and clarified instructions for production authentication, including detailed comments and links for setting up ClientSecretCredential and CertificateCredential, and emphasized the need to register an Azure AD application and configure permissions.
• Added a reference link to the Azure Identity documentation for further guidance.

Async client usage and documentation:

• Added notes and code comments throughout the async sections in both README.md and .claude/skills/dataverse-sdk-use/SKILL.md to clarify that async code fragments require an async def main() context, and that await cannot be used at the top level. [1] [2] [3] [4] [5] [6] [7]
• Updated async code snippets to show proper credential instantiation and improved context management examples. [1] [2] [3] [4]

Exception handling and troubleshooting:

• Added a comprehensive section detailing the SDK's exception hierarchy, including a diagram and table explaining when each error type is raised and how to handle them. Provided explicit examples for handling ValidationError, MetadataError, SQLParseError, HttpError, and network errors (httpx/aiohttp).
• Clarified that continue_on_error in batch operations only affects server-side failures, not client-side validation or metadata errors.

Code correctness and idiomatic usage:

• Updated all relationship and metadata access in code examples to use attribute access (e.g., result.lookup_schema_name) instead of dictionary-style access, reflecting the actual SDK API and improving code reliability. [1] [2] [3] [4] [5]
• Improved and corrected query builder examples to use realistic and relevant fields, such as using email and creditlimit instead of deprecated or less common fields.

Bulk and upsert operations:

• Added a new section with code for setting up alternate keys before performing upsert operations, clarifying the one-time setup required and how to check key status.
• Updated bulk update examples to use the correct field (exchangerate) and improved comments for clarity.

These changes collectively make the documentation more accurate, user-friendly, and robust for both synchronous and asynchronous SDK usage.

References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21]