surfdataverse 1.1.5__tar.gz

surfdataverse-1.1.5/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.3
+Name: surfdataverse
+Version: 1.1.5
+Summary: A Python package for ionysis Microsoft Dataverse integration
+Keywords: dataverse,microsoft,crm,api
+Author: ionysis
+Author-email: ionysis <friedemann.heinz@ionysis.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: msal>=1.33.0
+Requires-Dist: pandas>=2.3.2
+Requires-Dist: requests>=2.32.5
+Requires-Python: >=3.11
+Project-URL: Bug Tracker, https://github.com/FriedemannHeinz/SurfDataverse/issues
+Project-URL: Documentation, https://github.com/FriedemannHeinz/SurfDataverse#readme
+Project-URL: Homepage, https://github.com/FriedemannHeinz/SurfDataverse
+Project-URL: Repository, https://github.com/FriedemannHeinz/SurfDataverse.git
+Description-Content-Type: text/markdown
+
+# SurfDataverse
+
+A Python package for Microsoft Dataverse integration, providing a clean, object-oriented interface for connecting to, reading from, and writing to Microsoft Dataverse environments.
+
+## Features
+
+- **Easy Authentication**: Simplified MSAL-based authentication with token caching
+- **Object-Oriented Interface**: Work with Dataverse entities as Python objects
+- **Type Safety**: Built-in validation and error handling
+- **Configurable**: Support for multiple environments and configurations
+- **Extensible**: Easy to add new entity types and customize behavior
+
+## Installation
+
+### From Source
+```bash
+git clone https://github.com/FriedemannHeinz/SurfDataverse.git
+cd SurfDataverse
+pip install -e .
+```
+
+### Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+## Quick Start
+
+### 1. Configuration
+
+Create a configuration JSON file with your Dataverse connection details:
+
+```json
+{
+    "authorityBase": "https://login.microsoftonline.com/",
+    "tenantID": "your-tenant-id",
+    "clientID": "your-client-id", 
+    "environmentURI": "https://yourorg.crm.dynamics.com/",
+    "scopeSuffix": "/.default"
+}
+```
+
+### 2. Basic Usage
+
+```python
+from surf_dataverse import DataverseSession, Article, Recipe
+from pathlib import Path
+
+# Initialize session
+config_path = Path("connection_configs/your_config.json")
+session = DataverseSession(config_path=config_path)
+
+# Authenticate
+session.get_authenticated_session()
+
+# Test connection
+session.test_connection()
+
+# Create and work with entities
+article = Article()
+article.name = "My Product"
+article.company = "My Company"
+article.external_article_nr = "EXT-001"
+
+# Write to Dataverse
+article.write_to_dataverse()
+print(f"Created article with GUID: {article.guid}")
+```
+
+## Available Entities
+
+The package includes pre-built entity classes for:
+
+- **Article**: Product/item management
+- **Recipe**: Production recipes and formulations
+- **Ingredient**: Recipe components and quantities  
+- **Process**: Manufacturing processes
+- **Batch**: Production batches and lots
+- **Fabrication**: Manufacturing operations
+- **Consumption**: Resource consumption tracking
+- **Property**: Entity properties and attributes
+
+## Entity Properties
+
+Each entity provides property-based access to Dataverse fields:
+
+```python
+# Data properties (simple text/numeric fields)
+article.name = "Product Name"
+article.company = "Company Name"
+
+# Lookup properties (relationships to other entities)
+ingredient.article = article_guid  # Links to Article entity
+ingredient.recipe = recipe_guid    # Links to Recipe entity
+
+# Choice properties (option sets)
+recipe.type = "Production"  # Maps to numeric choice value
+```
+
+## Error Handling
+
+The package provides comprehensive error handling:
+
+```python
+from surf_dataverse import (
+    AuthenticationError,
+    ConnectionError, 
+    DataverseAPIError,
+    EntityError,
+    ValidationError
+)
+
+try:
+    session.get_authenticated_session()
+    article.write_to_dataverse()
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+except DataverseAPIError as e:
+    print(f"API error (status {e.status_code}): {e}")
+except ValidationError as e:
+    print(f"Data validation error: {e}")
+```
+
+## Advanced Usage
+
+### Custom Entity Classes
+
+Extend `DataverseRow` to create custom entity classes:
+
+```python
+from surf_dataverse import DataverseRow
+
+class MyCustomEntity(DataverseRow):
+    def __init__(self):
+        super().__init__('my_custom_table')
+    
+    # Define properties
+    name = DataverseRow.data_property('my_name_field')
+    category = DataverseRow.choice_property('my_category_field')  
+    parent = DataverseRow.lookup_property('my_parent_field')
+```
+
+### Session Management
+
+The `DataverseSession` uses a singleton pattern, so you can access the same session from anywhere:
+
+```python
+# First initialization
+session1 = DataverseSession(config_path="config1.json")
+
+# Later access (returns same instance)  
+session2 = DataverseSession()  # Same as session1
+```
+
+### Data Retrieval
+
+Fetch data from Dataverse tables:
+
+```python
+# Get table data as pandas DataFrame
+df = session.get_table_data(logical_name="iony_article")
+
+# Get specific record
+record = session.get_record("articles", "guid-here")
+
+# Get table metadata
+metadata = session.get_table_metadata("iony_article")
+```
+
+## Development
+
+### Project Structure
+```
+surf_dataverse/
+├── __init__.py          # Package initialization
+├── core.py              # Core session and entity classes
+├── entities.py          # Pre-built entity definitions
+└── exceptions.py        # Custom exceptions
+
+examples/
+└── basic_usage.py       # Usage examples
+
+connection_configs/      # Configuration files (not tracked)
+├── dev.json
+└── production.json
+```
+
+### Dependencies
+
+- `msal`: Microsoft Authentication Library
+- `requests`: HTTP client  
+- `pandas`: Data manipulation and analysis
+
+### Testing
+
+```bash
+pytest tests/
+```
+
+### Code Style
+
+```bash
+black surf_dataverse/
+flake8 surf_dataverse/
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+For issues and questions:
+- GitHub Issues: [https://github.com/FriedemannHeinz/SurfDataverse/issues](https://github.com/FriedemannHeinz/SurfDataverse/issues)
+- Documentation: This README and inline code documentation

surfdataverse-1.1.5/README.md

@@ -0,0 +1,223 @@
+# SurfDataverse
+
+A Python package for Microsoft Dataverse integration, providing a clean, object-oriented interface for connecting to, reading from, and writing to Microsoft Dataverse environments.
+
+## Features
+
+- **Easy Authentication**: Simplified MSAL-based authentication with token caching
+- **Object-Oriented Interface**: Work with Dataverse entities as Python objects
+- **Type Safety**: Built-in validation and error handling
+- **Configurable**: Support for multiple environments and configurations
+- **Extensible**: Easy to add new entity types and customize behavior
+
+## Installation
+
+### From Source
+```bash
+git clone https://github.com/FriedemannHeinz/SurfDataverse.git
+cd SurfDataverse
+pip install -e .
+```
+
+### Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+## Quick Start
+
+### 1. Configuration
+
+Create a configuration JSON file with your Dataverse connection details:
+
+```json
+{
+    "authorityBase": "https://login.microsoftonline.com/",
+    "tenantID": "your-tenant-id",
+    "clientID": "your-client-id", 
+    "environmentURI": "https://yourorg.crm.dynamics.com/",
+    "scopeSuffix": "/.default"
+}
+```
+
+### 2. Basic Usage
+
+```python
+from surf_dataverse import DataverseSession, Article, Recipe
+from pathlib import Path
+
+# Initialize session
+config_path = Path("connection_configs/your_config.json")
+session = DataverseSession(config_path=config_path)
+
+# Authenticate
+session.get_authenticated_session()
+
+# Test connection
+session.test_connection()
+
+# Create and work with entities
+article = Article()
+article.name = "My Product"
+article.company = "My Company"
+article.external_article_nr = "EXT-001"
+
+# Write to Dataverse
+article.write_to_dataverse()
+print(f"Created article with GUID: {article.guid}")
+```
+
+## Available Entities
+
+The package includes pre-built entity classes for:
+
+- **Article**: Product/item management
+- **Recipe**: Production recipes and formulations
+- **Ingredient**: Recipe components and quantities  
+- **Process**: Manufacturing processes
+- **Batch**: Production batches and lots
+- **Fabrication**: Manufacturing operations
+- **Consumption**: Resource consumption tracking
+- **Property**: Entity properties and attributes
+
+## Entity Properties
+
+Each entity provides property-based access to Dataverse fields:
+
+```python
+# Data properties (simple text/numeric fields)
+article.name = "Product Name"
+article.company = "Company Name"
+
+# Lookup properties (relationships to other entities)
+ingredient.article = article_guid  # Links to Article entity
+ingredient.recipe = recipe_guid    # Links to Recipe entity
+
+# Choice properties (option sets)
+recipe.type = "Production"  # Maps to numeric choice value
+```
+
+## Error Handling
+
+The package provides comprehensive error handling:
+
+```python
+from surf_dataverse import (
+    AuthenticationError,
+    ConnectionError, 
+    DataverseAPIError,
+    EntityError,
+    ValidationError
+)
+
+try:
+    session.get_authenticated_session()
+    article.write_to_dataverse()
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+except DataverseAPIError as e:
+    print(f"API error (status {e.status_code}): {e}")
+except ValidationError as e:
+    print(f"Data validation error: {e}")
+```
+
+## Advanced Usage
+
+### Custom Entity Classes
+
+Extend `DataverseRow` to create custom entity classes:
+
+```python
+from surf_dataverse import DataverseRow
+
+class MyCustomEntity(DataverseRow):
+    def __init__(self):
+        super().__init__('my_custom_table')
+    
+    # Define properties
+    name = DataverseRow.data_property('my_name_field')
+    category = DataverseRow.choice_property('my_category_field')  
+    parent = DataverseRow.lookup_property('my_parent_field')
+```
+
+### Session Management
+
+The `DataverseSession` uses a singleton pattern, so you can access the same session from anywhere:
+
+```python
+# First initialization
+session1 = DataverseSession(config_path="config1.json")
+
+# Later access (returns same instance)  
+session2 = DataverseSession()  # Same as session1
+```
+
+### Data Retrieval
+
+Fetch data from Dataverse tables:
+
+```python
+# Get table data as pandas DataFrame
+df = session.get_table_data(logical_name="iony_article")
+
+# Get specific record
+record = session.get_record("articles", "guid-here")
+
+# Get table metadata
+metadata = session.get_table_metadata("iony_article")
+```
+
+## Development
+
+### Project Structure
+```
+surf_dataverse/
+├── __init__.py          # Package initialization
+├── core.py              # Core session and entity classes
+├── entities.py          # Pre-built entity definitions
+└── exceptions.py        # Custom exceptions
+
+examples/
+└── basic_usage.py       # Usage examples
+
+connection_configs/      # Configuration files (not tracked)
+├── dev.json
+└── production.json
+```
+
+### Dependencies
+
+- `msal`: Microsoft Authentication Library
+- `requests`: HTTP client  
+- `pandas`: Data manipulation and analysis
+
+### Testing
+
+```bash
+pytest tests/
+```
+
+### Code Style
+
+```bash
+black surf_dataverse/
+flake8 surf_dataverse/
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+For issues and questions:
+- GitHub Issues: [https://github.com/FriedemannHeinz/SurfDataverse/issues](https://github.com/FriedemannHeinz/SurfDataverse/issues)
+- Documentation: This README and inline code documentation

surfdataverse-1.1.5/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["uv_build>=0.8.18,<0.9.0"]
+build-backend = "uv_build"
+
+[project]
+name = "surfdataverse"
+version = "1.1.5"
+description = "A Python package for ionysis Microsoft Dataverse integration"
+readme = "README.md"
+authors = [
+    {name = "ionysis", email = "friedemann.heinz@ionysis.com"}
+]
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers", 
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+keywords = ["dataverse", "microsoft", "crm", "api"]
+requires-python = ">=3.11"
+dependencies = [
+    "msal>=1.33.0",
+    "pandas>=2.3.2",
+    "requests>=2.32.5",
+]
+
+[dependency-groups]
+test = [
+    "pytest>=6.0",
+    "pytest-cov",
+    "pytest-mock",
+    "responses>=0.23.0"
+]
+typing = [
+    "mypy>=1.0.0",
+    "types-requests",
+    "pandas-stubs"
+]
+typing-test = [
+    {include-group = "typing"},
+    {include-group = "test"}
+]
+dev = [
+    "ruff>=0.0.241",
+    "uv-build>=0.8.18",
+]
+
+[project.urls]
+Homepage = "https://github.com/FriedemannHeinz/SurfDataverse"
+Repository = "https://github.com/FriedemannHeinz/SurfDataverse.git"
+Documentation = "https://github.com/FriedemannHeinz/SurfDataverse#readme"
+"Bug Tracker" = "https://github.com/FriedemannHeinz/SurfDataverse/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["surfdataverse*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]  # Error, pyflakes, warnings, import sorting
+ignore = ["E501"]  # Line too long (handled by formatter)
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

surfdataverse-1.1.5/src/surfdataverse/surfdataverse/__init__.py

@@ -0,0 +1,38 @@
+"""
+SurfDataverse - A Python package for Microsoft Dataverse integration
+
+This package provides a clean, object-oriented interface for connecting to,
+reading from, and writing to Microsoft Dataverse environments.
+
+Main Components:
+- DataverseClient: Authentication and connection management
+- DataverseRow: Base class for entity operations
+- Entity classes: Article, Recipe, Ingredient, etc.
+"""
+
+from .core import DataverseClient, DataverseTable
+from .exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    ConnectionError,
+    DataverseAPIError,
+    EntityError,
+    SurfDataverseError,
+    ValidationError,
+)
+from .tables import Tables
+
+__author__ = "Friedemann Heinz"
+
+__all__ = [
+    "DataverseClient",
+    "DataverseTable",
+    "Tables",
+    "SurfDataverseError",
+    "AuthenticationError",
+    "ConnectionError",
+    "ConfigurationError",
+    "DataverseAPIError",
+    "EntityError",
+    "ValidationError",
+]