feat: Complete SDK restructuring

examples/README.md

@@ -0,0 +1,59 @@
+# Dataverse SDK Examples
+
+This directory contains comprehensive examples demonstrating how to use the Microsoft Dataverse SDK for Python.
+
+## 📁 Directory Structure
+
+### 🌱 Basic Examples (`basic/`)
+Get started quickly with fundamental Dataverse operations:
+- **`quickstart.py`** - Basic client setup, authentication, and simple CRUD operations
+- Authentication setup with Azure Identity
+- Creating, reading, updating, and deleting records
+- Basic error handling
+
+### 🚀 Advanced Examples (`advanced/`)
+Explore powerful features for complex scenarios:
+- **`file_upload.py`** - File upload to Dataverse file columns with chunking
+- **`pandas_integration.py`** - DataFrame-based operations for data analysis
+
+## 🚀 Getting Started
+
+1. **Install Dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. **Set Up Authentication**:
+   Configure Azure Identity credentials (see individual examples for details)
+
+3. **Run Basic Example**:
+   ```bash
+   python examples/basic/quickstart.py
+   ```
+
+## 📋 Prerequisites
+
+- Python 3.8+
+- Azure Identity credentials configured
+- Access to a Dataverse environment
+- Required packages installed from `requirements.txt`
+
+## 🔒 Authentication
+
+All examples use Azure Identity for authentication. Common patterns:
+- `DefaultAzureCredential` for development
+- `ClientSecretCredential` for production services
+- `InteractiveBrowserCredential` for interactive scenarios
+
+## 📖 Documentation
+
+For detailed API documentation, visit: [Dataverse SDK Documentation](link-to-docs)
+
+## 🤝 Contributing
+
+When adding new examples:
+1. Follow the existing code style and structure
+2. Include comprehensive comments and docstrings
+3. Add error handling and validation
+4. Update this README with your example
+5. Test thoroughly before submitting

examples/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Examples package for the Dataverse SDK."""

examples/advanced/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Advanced examples showcasing complex Dataverse SDK features."""

examples/quickstart_pandas.py → examples/advanced/pandas_integration.py

@@ -9,7 +9,7 @@
 sys.path.append(str(Path(__file__).resolve().parents[1] / "src"))
 
 from dataverse_sdk import DataverseClient
-from dataverse_sdk.odata_pandas_wrappers import PandasODataClient
+from dataverse_sdk.utils.pandas_adapter import PandasODataClient
 from azure.identity import InteractiveBrowserCredential
 import traceback
 import requests

examples/basic/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Basic examples for getting started with the Dataverse SDK."""

examples/quickstart.py → examples/basic/quickstart.py

@@ -10,7 +10,7 @@
 sys.path.append(str(Path(__file__).resolve().parents[1] / "src"))
 
 from dataverse_sdk import DataverseClient
-from dataverse_sdk.errors import MetadataError
+from dataverse_sdk.core.errors import MetadataError
 from enum import IntEnum
 from azure.identity import InteractiveBrowserCredential
 import traceback

src/dataverse_sdk/client.py

@@ -7,9 +7,9 @@
 
 from azure.core.credentials import TokenCredential
 
-from .auth import AuthManager
-from .config import DataverseConfig
-from .odata import ODataClient
+from .core.auth import AuthManager
+from .core.config import DataverseConfig
+from .data.odata import ODataClient
 
 
 class DataverseClient:

src/dataverse_sdk/core/__init__.py

@@ -0,0 +1,32 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""
+Core infrastructure components for the Dataverse SDK.
+
+This module contains the foundational components including authentication,
+configuration, HTTP client, and error handling.
+"""
+
+from .auth import AuthManager, TokenPair
+from .config import DataverseConfig
+from .errors import (
+    DataverseError,
+    HttpError,
+    ValidationError,
+    MetadataError,
+    SQLParseError,
+)
+from .http import HttpClient
+
+__all__ = [
+    "AuthManager",
+    "TokenPair",
+    "DataverseConfig",
+    "DataverseError",
+    "HttpError",
+    "ValidationError",
+    "MetadataError",
+    "SQLParseError",
+    "HttpClient",
+]

src/dataverse_sdk/data/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""
+Data access layer for the Dataverse SDK.
+
+This module contains OData protocol handling, CRUD operations, metadata management,
+SQL query functionality, and file upload capabilities.
+"""
+
+from .odata import ODataClient
+from .upload import ODataFileUpload
+
+__all__ = ["ODataClient", "ODataFileUpload"]

src/dataverse_sdk/odata.py → src/dataverse_sdk/data/odata.py

@@ -12,10 +12,10 @@
 from datetime import datetime, timezone
 import importlib.resources as ir
 
-from .http import HttpClient
-from .odata_upload_files import ODataFileUpload
-from .errors import *
-from . import error_codes as ec
+from ..core.http import HttpClient
+from .upload import ODataFileUpload
+from ..core.errors import *
+from ..core import error_codes as ec
 
 
 _GUID_RE = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")
@@ -40,7 +40,7 @@ def __init__(
         if not self.base_url:
             raise ValueError("base_url is required.")
         self.api = f"{self.base_url}/api/data/v9.2"
-        self.config = config or __import__("dataverse_sdk.config", fromlist=["DataverseConfig"]).DataverseConfig.from_env()
+        self.config = config or __import__("dataverse_sdk.core.config", fromlist=["DataverseConfig"]).DataverseConfig.from_env()
         self._http = HttpClient(
             retries=self.config.http_retries,
             backoff=self.config.http_backoff,

src/dataverse_sdk/extensions/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""
+Optional extensions for the Dataverse SDK.
+
+This module contains optional features like CLI interfaces, async clients,
+and other extended functionality.
+"""
+
+# Will be populated with extensions as they are created
+__all__ = []

src/dataverse_sdk/models/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""
+Data models and type definitions for the Dataverse SDK.
+
+This module contains entity models, response models, enums, and other
+type definitions used throughout the SDK.
+"""
+
+# Will be populated with models as they are created
+__all__ = []

src/dataverse_sdk/utils/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""
+Utilities and adapters for the Dataverse SDK.
+
+This module contains helper functions, adapters (like Pandas integration),
+logging utilities, and validation helpers.
+"""
+
+from .pandas_adapter import PandasODataClient
+
+__all__ = ["PandasODataClient"]

src/dataverse_sdk/odata_pandas_wrappers.py → src/dataverse_sdk/utils/pandas_adapter.py

@@ -17,7 +17,7 @@
 
 import pandas as pd
 
-from .odata import ODataClient
+from ..data.odata import ODataClient
 
 
 @dataclass

tests/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Test package for the Dataverse SDK."""

tests/conftest.py

@@ -0,0 +1,65 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""
+Shared pytest fixtures and configuration for Dataverse SDK tests.
+
+This module provides common test fixtures, mock objects, and configuration
+that can be used across all test modules.
+"""
+
+import pytest
+from unittest.mock import Mock
+from dataverse_sdk.core.config import DataverseConfig
+
+
+@pytest.fixture
+def dummy_auth():
+    """Mock authentication object for testing."""
+    class DummyAuth:
+        def acquire_token(self, scope):
+            class Token:
+                access_token = "test_token_12345"
+            return Token()
+    return DummyAuth()
+
+
+@pytest.fixture  
+def test_config():
+    """Test configuration with safe defaults."""
+    return DataverseConfig(
+        language_code=1033,
+        http_retries=0,
+        http_backoff=0.1,
+        http_timeout=5
+    )
+
+
+@pytest.fixture
+def mock_http_client():
+    """Mock HTTP client for unit tests."""
+    mock = Mock()
+    mock.request.return_value = Mock()
+    return mock
+
+
+@pytest.fixture
+def sample_base_url():
+    """Standard test base URL."""
+    return "https://org.example.com"
+
+
+@pytest.fixture
+def sample_entity_data():
+    """Sample entity data for testing."""
+    return {
+        "name": "Test Account",
+        "telephone1": "555-0100", 
+        "websiteurl": "https://example.com"
+    }
+
+
+@pytest.fixture
+def sample_guid():
+    """Sample GUID for testing."""
+    return "11111111-2222-3333-4444-555555555555"

tests/fixtures/test_data.py

@@ -0,0 +1,69 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""
+Sample test data and fixtures for Dataverse SDK tests.
+
+This module contains reusable test data, mock responses, and fixtures
+that can be used across different test modules.
+"""
+
+# Sample entity metadata response
+SAMPLE_ENTITY_METADATA = {
+    "value": [
+        {
+            "LogicalName": "account",
+            "EntitySetName": "accounts", 
+            "PrimaryIdAttribute": "accountid",
+            "DisplayName": {"UserLocalizedLabel": {"Label": "Account"}}
+        },
+        {
+            "LogicalName": "contact",
+            "EntitySetName": "contacts",
+            "PrimaryIdAttribute": "contactid", 
+            "DisplayName": {"UserLocalizedLabel": {"Label": "Contact"}}
+        }
+    ]
+}
+
+# Sample OData response for accounts
+SAMPLE_ACCOUNTS_RESPONSE = {
+    "value": [
+        {
+            "accountid": "11111111-2222-3333-4444-555555555555",
+            "name": "Contoso Ltd",
+            "telephone1": "555-0100",
+            "websiteurl": "https://contoso.com"
+        },
+        {
+            "accountid": "22222222-3333-4444-5555-666666666666", 
+            "name": "Fabrikam Inc",
+            "telephone1": "555-0200",
+            "websiteurl": "https://fabrikam.com"
+        }
+    ]
+}
+
+# Sample error responses
+SAMPLE_ERROR_RESPONSES = {
+    "404": {
+        "error": {
+            "code": "0x80040217",
+            "message": "The requested resource was not found."
+        }
+    },
+    "429": {
+        "error": {
+            "code": "0x80072321", 
+            "message": "Too many requests. Please retry after some time."
+        }
+    }
+}
+
+# Sample SQL query results
+SAMPLE_SQL_RESPONSE = {
+    "value": [
+        {"name": "Account 1", "revenue": 1000000},
+        {"name": "Account 2", "revenue": 2000000}
+    ]
+}

tests/integration/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Integration tests for the Dataverse SDK."""

tests/unit/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Unit tests for the Dataverse SDK."""

tests/unit/core/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Unit tests for core infrastructure components."""