surfdataverse 2.1.0__tar.gz → 3.0.0__tar.gz

{surfdataverse-2.1.0 → surfdataverse-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: surfdataverse
-Version: 2.1.0
+Version: 3.0.0
 Summary: A Python package for ionysis Microsoft Dataverse integration
 Keywords: dataverse,microsoft,crm,api
 Author: ionysis
@@ -14,9 +14,11 @@ 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: dependency-injector>=4.42.0
 Requires-Dist: msal>=1.33.0
 Requires-Dist: numpy>=2.3.3
 Requires-Dist: pandas>=2.3.2
+Requires-Dist: polars>=1.34.0
 Requires-Dist: requests>=2.32.5
 Requires-Python: >=3.11
 Project-URL: Bug Tracker, https://github.com/FriedemannHeinz/SurfDataverse/issues
@@ -222,11 +224,12 @@ For custom scenarios, you can create properties manually:
 ```python
 from surfdataverse import DataverseTable
 
+
 # Extend the base class
 class CustomTable(DataverseTable):
     def __init__(self, logical_name, prefix="prefix_"):
-        super().__init__(logical_name, table_prefix=prefix)
-    
+        super().__init__(logical_name, prefix=prefix)
+
     # Add custom business logic
     def validate_data(self):
         if not self.name:

{surfdataverse-2.1.0 → surfdataverse-3.0.0}/README.md

@@ -195,11 +195,12 @@ For custom scenarios, you can create properties manually:
 ```python
 from surfdataverse import DataverseTable
 
+
 # Extend the base class
 class CustomTable(DataverseTable):
     def __init__(self, logical_name, prefix="prefix_"):
-        super().__init__(logical_name, table_prefix=prefix)
-    
+        super().__init__(logical_name, prefix=prefix)
+
     # Add custom business logic
     def validate_data(self):
         if not self.name:

{surfdataverse-2.1.0 → surfdataverse-3.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "surfdataverse"
-version = "2.1.0"
+version = "3.0.0"
 description = "A Python package for ionysis Microsoft Dataverse integration"
 readme = "README.md"
 authors = [
@@ -24,9 +24,11 @@ classifiers = [
 keywords = ["dataverse", "microsoft", "crm", "api"]
 requires-python = ">=3.11"
 dependencies = [
+    "dependency-injector>=4.42.0",
     "msal>=1.33.0",
     "numpy>=2.3.3",
     "pandas>=2.3.2",
+    "polars>=1.34.0",
     "requests>=2.32.5",
 ]
 

{surfdataverse-2.1.0 → surfdataverse-3.0.0}/src/surfdataverse/__init__.py

@@ -10,7 +10,8 @@ Main Components:
 - Entity classes: Article, Recipe, Ingredient, etc.
 """
 
-from .core import DataverseClient, DataverseTable, is_valid_guid
+from .container import connect_entity, connect_table, container, get_client, reset_container
+from .core import DataverseClient, DataverseEntity, DataverseTable, is_valid_guid
 from .exceptions import (
     AuthenticationError,
     ConfigurationError,
@@ -26,7 +27,13 @@ __author__ = "Friedemann Heinz"
 __all__ = [
     "DataverseClient",
     "DataverseTable",
+    "DataverseEntity",
     "is_valid_guid",
+    "get_client",
+    "connect_table",
+    "connect_entity",
+    "reset_container",
+    "container",
     "SurfDataverseError",
     "AuthenticationError",
     "ConnectionError",

surfdataverse-3.0.0/src/surfdataverse/container.py

@@ -0,0 +1,49 @@
+"""
+Dependency injection container for SurfDataverse.
+"""
+
+from dependency_injector import containers, providers
+
+from .core import DataverseClient, DataverseEntity, DataverseTable
+
+
+class Container(containers.DeclarativeContainer):
+    """Main dependency injection container for SurfDataverse"""
+
+    # Configuration
+    config = providers.Configuration()
+
+    # Core client as singleton
+    client = providers.Singleton(DataverseClient, config_path=config.config_path)
+
+    # Table factory - creates DataverseTable instances with injected client
+    table_factory = providers.Factory(DataverseTable, client=client)
+
+    # Entity factory - creates DataverseEntity instances with injected client
+    entity_factory = providers.Factory(DataverseEntity, client=client)
+
+
+# Global container instance
+container = Container()
+
+
+def get_client(config_path=None) -> DataverseClient:
+    """Get the singleton DataverseClient instance"""
+    if config_path:
+        container.config.config_path.from_value(config_path)
+    return container.client()
+
+
+def connect_table(logical_name: str = "", prefix: str = "") -> DataverseTable:
+    """Connect to a Dataverse table"""
+    return container.table_factory(logical_name, prefix)
+
+
+def connect_entity(table_logical_name: str, table_prefix: str = "") -> DataverseEntity:
+    """Connect to a new Dataverse entity instance"""
+    return container.entity_factory(table_logical_name, table_prefix)
+
+
+def reset_container():
+    """Reset the container - useful for testing"""
+    container.reset_singletons()

{surfdataverse-2.1.0 → surfdataverse-3.0.0}/src/surfdataverse/core.py

@@ -4,13 +4,13 @@ import logging
 import sys
 import uuid
 from decimal import Decimal
-from enum import Enum
 from pathlib import Path
 from typing import Optional
 
 import msal
 import pandas as pd
 import requests
+from pandas.io.sql import table_exists
 
 from .exceptions import (
     AuthenticationError,
@@ -45,22 +45,20 @@ def user_config_dir(app_name: str, company: str) -> Path:
     return app_config_dir
 
 
-class SingletonMeta(type):
-    """Metaclass for creating a Singleton."""
+# Singleton pattern now handled by dependency injection container
 
-    _instances: dict = {}
-
-    def __call__(cls, *args, **kwargs):
-        if cls not in cls._instances:
-            cls._instances[cls] = super().__call__(*args, **kwargs)
-        return cls._instances[cls]
 
+def is_valid_guid(value: str) -> bool:
+    """Returns True if the value is a valid GUID, otherwise False."""
+    try:
+        uuid_obj = uuid.UUID(value)  # Ensure it's a valid UUID
+        return str(uuid_obj) == value.lower()  # Ensure correct format
+    except ValueError:
+        return False
 
-class DataverseClient(metaclass=SingletonMeta):
-    def __init__(self, config_path=None, *args):
-        if hasattr(self, "_initialized"):
-            return  # Prevent reinitialization
 
+class DataverseClient:
+    def __init__(self, config_path=None):
         self.connected = False
         self.session = requests.Session()
         self.environment_uri: str = ""
@@ -69,18 +67,6 @@ class DataverseClient(metaclass=SingletonMeta):
         self.account = None  # Store the logged-in account
         self.config_path = config_path
 
-        if "xml" in args:
-            self.filetype = "xml"
-        else:
-            self.filetype = "json"
-
-        # Stored values for this session
-        self._table_metadata = {}
-        self._global_choices = {}
-        self._guid_mapping = {}
-        self._table_definitions = {}
-        self._relationships = {}
-
     # === CONNECTION, AUTHENTICATION, TEST
     def get_authenticated_session(self, config_json: Optional[str | Path] = None):
         if config_json is None and self.config_path is None:
@@ -131,7 +117,7 @@ class DataverseClient(metaclass=SingletonMeta):
                     "OData-Version": "4.0",
                     "If-None-Match": "null",
                     "Prefer": 'odata.include-annotations="*"',
-                    "Accept": f"application/{self.filetype}",
+                    "Accept": "application/json",
                 }
             )
             with open(cache_file, "w") as f:
@@ -192,14 +178,37 @@ class DataverseClient(metaclass=SingletonMeta):
         except requests.RequestException as e:
             raise ConnectionError(f"Network error during connection test: {str(e)}")
 
+
+class DataverseBase:
+    """Base class for Dataverse operations with shared functionality"""
+
+    def __init__(self, table_logical_name: str = "", prefix="", client=None):
+        self.client = client or DataverseClient()
+
+        self.table_logical_name = table_logical_name
+        self.table_logical_name_prefix = prefix
+        self.name = (
+            table_logical_name.replace(self.table_logical_name_prefix, "").title().replace("_", " ")
+        )
+
+        # Stored values for this session
+        self._guid_mapping = {}
+        self._all_relationships = {}  # Populated by first call
+        self._global_choices = {}  # Populated by first call
+
+        self._table_metadata = {}
+        self._table_definitions = {}
+        self._table_relationships = {}
+        self._filtered_choices = {}
+
     # === RELATIONSHIPS
     @property
-    def relationships(self):
-        if not self._relationships:
-            request_uri = f"{self.environment_uri}api/data/v9.2/RelationshipDefinitions"
-            response = self.session.get(request_uri)
+    def all_relationships(self):
+        if not self._all_relationships:
+            request_uri = f"{self.client.environment_uri}api/data/v9.2/RelationshipDefinitions"
+            response = self.client.session.get(request_uri)
             if response.status_code == 200:
-                self._relationships = response.json()
+                self._all_relationships = response.json()
             else:
                 logger.error(f"Error fetching relationships: {response.text}")
                 raise DataverseAPIError(
@@ -207,12 +216,12 @@ class DataverseClient(metaclass=SingletonMeta):
                     response.status_code,
                     response.text,
                 )
-        return self._relationships
+        return self._all_relationships
 
     # === FLOWS
     def get_flows(self):
-        request_uri = f"{self.environment_uri}api/data/v9.2/workflows"
-        response = self.session.get(request_uri)
+        request_uri = f"{self.client.environment_uri}api/data/v9.2/workflows"
+        response = self.client.session.get(request_uri)
         if response.status_code == 401:
             raise AuthenticationError("Unauthorized. Check your credentials and permissions.")
         elif response.status_code != 200:
@@ -226,8 +235,8 @@ class DataverseClient(metaclass=SingletonMeta):
     def global_choices(self):
         """Fetch all global choices (option sets) from Dataverse"""
         if not self._global_choices:
-            request_uri = f"{self.environment_uri}api/data/v9.2/GlobalOptionSetDefinitions"
-            response = self.session.get(request_uri)
+            request_uri = f"{self.client.environment_uri}api/data/v9.2/GlobalOptionSetDefinitions"
+            response = self.client.session.get(request_uri)
 
             if response.status_code == 200:
                 choices_data = response.json().get("value", [])
@@ -253,11 +262,22 @@ class DataverseClient(metaclass=SingletonMeta):
 
         return self._global_choices
 
+    @property
+    def filtered_choices(self):
+        """Get choices filtered by table prefix"""
+        if not self._filtered_choices:
+            self._filtered_choices = {
+                name: options
+                for name, options in self.global_choices.items()
+                if self.table_logical_name_prefix in name
+            }
+        return self._filtered_choices
+
     # === TABLES
     def get_table_definitions(self):
         if not self._table_definitions:
-            request_uri = f"{self.environment_uri}api/data/v9.2/EntityDefinitions"
-            response = self.session.get(request_uri)
+            request_uri = f"{self.client.environment_uri}api/data/v9.2/EntityDefinitions"
+            response = self.client.session.get(request_uri)
             if response.status_code == 200:
                 self._table_definitions = response.json()
             else:
@@ -269,10 +289,24 @@ class DataverseClient(metaclass=SingletonMeta):
                 )
         return self._table_definitions
 
+    def get_table_relationships(self) -> dict:
+        """Fetches all possible lookups (relationships) for this entity."""
+        result = self.all_relationships
+
+        if not self._table_relationships:
+            _relationships = {}
+            for rel in result.get("value", []):
+                if rel.get("ReferencingEntity") == self.table_logical_name:
+                    # Store lookup column name -> related entity table
+                    if "ReferencingAttribute" in rel and "ReferencedEntity" in rel:
+                        _relationships[rel["ReferencingAttribute"]] = rel["ReferencedEntity"]
+            self._table_relationships = _relationships
+        return self._table_relationships
+
     def get_table_metadata_raw(self, table_logical_name):
         """Fetch column metadata for a specific Dataverse table"""
-        request_uri = f"{self.environment_uri}api/data/v9.2/EntityDefinitions(LogicalName='{table_logical_name}')?$expand=Attributes"
-        response = self.session.get(request_uri)
+        request_uri = f"{self.client.environment_uri}api/data/v9.2/EntityDefinitions(LogicalName='{table_logical_name}')?$expand=Attributes"
+        response = self.client.session.get(request_uri)
 
         if response.status_code == 200:
             return response.json()  # Full metadata response
@@ -281,8 +315,10 @@ class DataverseClient(metaclass=SingletonMeta):
             logger.error(error_msg)
             raise DataverseAPIError(error_msg, response.status_code, response.text)
 
-    def get_table_metadata(self, table_logical_name):
+    def get_table_metadata(self, table_logical_name=None):
         """Finds fields that users can set in create/update operations"""
+        if table_logical_name is None:
+            table_logical_name = self.table_logical_name
         if table_logical_name not in self._table_metadata:
             raw_metadata = self.get_table_metadata_raw(table_logical_name)
             if not raw_metadata:
@@ -310,13 +346,120 @@ class DataverseClient(metaclass=SingletonMeta):
 
         return self._table_metadata[table_logical_name]
 
-    def get_table_data(
-        self, logical_name=None, entity_set_name=None, polars=False
-    ) -> pd.DataFrame | None:
-        """Fetches actual data from a given table (by LogicalName)
+    # === RECORDS
+    def get_record(self, entity_set_name, record_id):
+        """Fetches a newly created record by ID to retrieve auto-generated fields."""
+        request_uri = f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}({record_id})"
+        response = self.client.session.get(request_uri)
+
+        if response.status_code == 200:
+            return response.json()
+        else:
+            error_msg = f"Error fetching record: {response.text}"
+            logger.error(error_msg)
+            raise DataverseAPIError(error_msg, response.status_code, response.text)
+
+    # === HELPER METHODS
+    def name_to_guid(self, table_name, name=None, name_column=None) -> uuid.UUID | None:
+        """
+        Fetches a mapping of unique names to GUIDs in a Dataverse table
+
+        Args:
+            table_name: logical_name of table
+            name: name to map to guid
+            name_column: The column name to use for lookup (if not provided, will be inferred)
+
+        Returns:
+
+        """
+        # If name_column not provided, try to infer it
+        if not name_column:
+            # Extract prefix from table name
+            if "_" in table_name:
+                prefix = table_name.split("_")[0] + "_"
+                table_suffix = table_name.replace(prefix, "")
+
+                if table_suffix in ["article", "batch"]:
+                    name_column = table_name + "nr"
+                elif table_suffix == "r2rsession":
+                    name_column = f"{prefix}sessionid"
+                else:
+                    name_column = f"{prefix}name"  # Default fallback
+            else:
+                # For tables without prefix, assume standard naming
+                name_column = table_name + "name"
+
+        guid_column = table_name + "id"
+
+        def update_mapping():
+            entity_set_name = self.get_table_entity_set_name(logical_name=table_name)
+            request_uri = f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}?$select={name_column},{guid_column}"
+
+            response = self.client.session.get(request_uri)
+
+            if response.status_code == 200:
+                records = response.json().get("value", [])
+                mapping = {
+                    record[name_column]: record[guid_column]
+                    for record in records
+                    if name_column in record and guid_column in record
+                }
+                self._guid_mapping[table_name] = mapping
+            else:
+                error_msg = (
+                    f"Error fetching data from {table_name} for guid mapping: {response.text}"
+                )
+                logger.error(error_msg)
+                raise DataverseAPIError(error_msg, response.status_code, response.text)
+
+        if table_name not in self._guid_mapping:
+            update_mapping()
+
+        if name:
+            guid = self._guid_mapping[table_name].get(name, None)
+            if not guid:
+                raise EntityError(f"{name} not found in {table_name}")
+            else:
+                return guid
+        else:
+            return None
+
+    def get_table_of_guid(self, guid):
+        return next(
+            (
+                key
+                for key, value in self._guid_mapping.items()
+                if guid in [guid for guid in value.values()]
+            ),
+            None,
+        )
+
+    def get_table_entity_set_name(self, schema_name=None, logical_name=None):
+        tables = self.get_table_definitions()
+
+        if schema_name:
+            key = "SchemaName"
+            name = schema_name
+        elif logical_name:
+            key = "LogicalName"
+            name = logical_name
+        else:
+            raise ValueError("Please input schema or logical name")
+
+        for entity in tables["value"]:
+            if name == entity[key]:
+                return entity["EntitySetName"]
+        raise EntityError(f"{key} not found for {name}")
+
+
+class DataverseTable(DataverseBase):
+    """Table-level operations for Dataverse - inherits shared functionality from DataverseBase"""
+
+    # === TABLES
+    def get_table_data(self, table_logical_name = None, polars=False):
+        """Fetches actual data from this table
         Args:
-            logical_name: The logical name of the table
-            entity_set_name: The entity set name (alternative to logical_name)
+            table_logical_name: logical name of the table (optional)
             polars: Return Polars DataFrame instead of pandas
         """
 
@@ -332,16 +475,10 @@ class DataverseClient(metaclass=SingletonMeta):
             df = pl.DataFrame(data_list)
             return df
 
-        if entity_set_name:
-            pass
-        elif logical_name and not entity_set_name:
-            entity_set_name = self.get_table_entity_set_name(logical_name=logical_name)
-        else:
-            logger.info("Please provide logical or entity set name")
-            return None
+        entity_set_name = self.get_table_entity_set_name(logical_name=self.table_logical_name or table_logical_name)
 
-        request_uri = f"{self.environment_uri}api/data/v9.2/{entity_set_name}"
-        response = self.session.get(request_uri)
+        request_uri = f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}"
+        response = self.client.session.get(request_uri)
 
         if response.status_code == 200:
             return entity_to_polars(response.json()) if polars else entity_to_df(response.json())
@@ -350,7 +487,78 @@ class DataverseClient(metaclass=SingletonMeta):
             logger.error(error_msg)
             raise DataverseAPIError(error_msg, response.status_code, response.text)
 
-    def download_tables_as_df(self, schema_filter=None):
+    def get_column_data(self, columns, entity_set_name=None, polars=False):
+        """Fetches specific column data from this table
+        Args:
+            columns: Column name (string) or list of column names to retrieve
+            entity_set_name: The entity set name (optional, will be auto-determined)
+            polars: Return Polars DataFrame/Series instead of pandas
+        Returns:
+            pandas.Series (single column) or pandas.DataFrame (multiple columns)
+        """
+
+        def entity_to_df(entity_data, cols):
+            data_list = entity_data["value"]
+            df = pd.DataFrame(data_list)
+            # Return only requested columns that exist in the data
+            available_cols = [col for col in cols if col in df.columns]
+            if not available_cols:
+                logger.warning(f"None of the requested columns {cols} found in data")
+                return pd.DataFrame() if len(cols) > 1 else pd.Series(dtype=object)
+            result = df[available_cols]
+            return (
+                result.iloc[:, 0]
+                if len(available_cols) == 1 and isinstance(columns, str)
+                else result
+            )
+
+        def entity_to_polars(entity_data, cols):
+            import polars as pl
+
+            data_list = entity_data["value"]
+            df = pl.DataFrame(data_list)
+            # Return only requested columns that exist in the data
+            available_cols = [col for col in cols if col in df.columns]
+            if not available_cols:
+                logger.warning(f"None of the requested columns {cols} found in data")
+                return pl.DataFrame() if len(cols) > 1 else pl.Series(dtype=pl.Null)
+            result = df.select(available_cols)
+            return (
+                result.to_series()
+                if len(available_cols) == 1 and isinstance(columns, str)
+                else result
+            )
+
+        # Handle single column vs list of columns
+        if isinstance(columns, str):
+            column_list = [columns]
+        elif isinstance(columns, list):
+            column_list = columns
+        else:
+            raise ValueError("columns must be a string or list of strings")
+
+        if not entity_set_name:
+            entity_set_name = self.get_table_entity_set_name(logical_name=self.table_logical_name)
+
+        # Build OData $select query for specific columns
+        select_clause = ",".join(column_list)
+        request_uri = (
+            f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}?$select={select_clause}"
+        )
+        response = self.client.session.get(request_uri)
+
+        if response.status_code == 200:
+            return (
+                entity_to_polars(response.json(), column_list)
+                if polars
+                else entity_to_df(response.json(), column_list)
+            )
+        else:
+            error_msg = f"Failed to retrieve column data for {entity_set_name}: {response.text}"
+            logger.error(error_msg)
+            raise DataverseAPIError(error_msg, response.status_code, response.text)
+
+    def download_tables_as_df(self, schema_filter=None) -> tuple[dict, dict, dict]:
         """Download all tables as DataFrames, optionally filtered by schema name
 
         Args:
@@ -368,19 +576,18 @@ class DataverseClient(metaclass=SingletonMeta):
                 continue
 
             if table["DisplayName"]["UserLocalizedLabel"]:
-                logical_name = table["LogicalName"]
-                table_name = logical_name
+                table_logical_name = table["LogicalName"]
 
                 # Get selected definitions
-                _table_definitions[table_name] = table
+                _table_definitions[table_logical_name] = table
 
                 # Get data
-                _table_data[table_name] = self.get_table_data(logical_name=logical_name)
-                if _table_data[table_name] is None:
-                    return
+                _table_data[table_logical_name] = self.get_table_data(table_logical_name=table_logical_name)
+                if _table_data[table_logical_name] is None:
+                    return {}, {}, {}
 
                 # Get metadata
-                _table_metadata[table_name] = self.get_table_metadata(logical_name) or {}
+                _table_metadata[table_logical_name] = self.get_table_metadata(table_logical_name) or {}
 
         return _table_definitions, _table_data, _table_metadata
 
@@ -450,270 +657,93 @@ class DataverseClient(metaclass=SingletonMeta):
 
         return df_transformed
 
-    # === RECORDS
-    def get_record(self, entity_set_name, record_id):
-        """Fetches a newly created record by ID to retrieve auto-generated fields."""
-        request_uri = f"{self.environment_uri}api/data/v9.2/{entity_set_name}({record_id})"
-        response = self.session.get(request_uri)
-
-        if response.status_code == 200:
-            return response.json()  # Return the full record with auto-filled values
-        else:
-            error_msg = f"Error fetching record: {response.text}"
-            logger.error(error_msg)
-            raise DataverseAPIError(error_msg, response.status_code, response.text)
-
-    # === HELPER METHODS
-    def get_guid_by_casual_name(self, table_name, data, name_column=None) -> uuid.UUID | None:
-        """
-        Map display names to GUIDs if row exists
-
-        Args:
-            table_name: logical_name of table
-            data: data which holds the name to map to guid
-            name_column: The column name to use for lookup (if not provided, will be inferred)
-
-        Returns:
-
-        """
-        # If name_column not provided, try to infer it
-        if not name_column:
-            # Extract prefix from table name
-            if "_" in table_name:
-                prefix = table_name.split("_")[0] + "_"
-                table_suffix = table_name.replace(prefix, "")
-
-                if table_suffix == "recipe":
-                    name_column = f"{prefix}namecasual"
-                elif table_suffix == "article":
-                    name_column = f"{prefix}name"
-                elif table_suffix == "r2rsession":
-                    name_column = f"{prefix}sessionid"
-                else:
-                    name_column = f"{prefix}name"  # Default fallback
-            else:
-                raise EntityError(
-                    f"Cannot infer name column for {table_name}. Please provide name_column parameter."
-                )
-
-        guid_column = table_name + "id"
-
-        name = data[name_column]
-
-        entity_set_name = self.get_table_entity_set_name(logical_name=table_name)
-        request_uri = f"{self.environment_uri}api/data/v9.2/{entity_set_name}?$select={name_column},{guid_column}"
-
-        response = self.session.get(request_uri)
-
-        if response.status_code == 200:
-            records = response.json().get("value", [])
-            mapping = {
-                record[name_column]: record[guid_column]
-                for record in records
-                if name_column in record and guid_column in record
-            }
-            return mapping.get(name, None)
-        else:
-            error_msg = (
-                f"Error fetching data from {table_name} for row existence check: {response.text}"
-            )
-            logger.error(error_msg)
-            raise DataverseAPIError(error_msg, response.status_code, response.text)
-
-    def name_to_guid(self, table_name, name=None, name_column=None) -> uuid.UUID | None:
-        """
-        Fetches a mapping of unique names to GUIDs in a Dataverse table
-
-        Args:
-            table_name: logical_name of table
-            name: name to map to guid
-            name_column: The column name to use for lookup (if not provided, will be inferred)
-
-        Returns:
-
-        """
-        # If name_column not provided, try to infer it
-        if not name_column:
-            # Extract prefix from table name
-            if "_" in table_name:
-                prefix = table_name.split("_")[0] + "_"
-                table_suffix = table_name.replace(prefix, "")
-
-                if table_suffix in ["article", "batch"]:
-                    name_column = table_name + "nr"
-                elif table_suffix == "r2rsession":
-                    name_column = f"{prefix}sessionid"
-                else:
-                    name_column = f"{prefix}name"  # Default fallback
-            else:
-                # For tables without prefix, assume standard naming
-                name_column = table_name + "name"
-
-        guid_column = table_name + "id"
-
-        def update_mapping():
-            entity_set_name = self.get_table_entity_set_name(logical_name=table_name)
-            request_uri = f"{self.environment_uri}api/data/v9.2/{entity_set_name}?$select={name_column},{guid_column}"
-
-            response = self.session.get(request_uri)
-
-            if response.status_code == 200:
-                records = response.json().get("value", [])
-                mapping = {
-                    record[name_column]: record[guid_column]
-                    for record in records
-                    if name_column in record and guid_column in record
-                }
-                self._guid_mapping[table_name] = mapping
-            else:
-                error_msg = (
-                    f"Error fetching data from {table_name} for guid mapping: {response.text}"
-                )
-                logger.error(error_msg)
-                raise DataverseAPIError(error_msg, response.status_code, response.text)
-
-        if table_name not in self._guid_mapping:
-            update_mapping()
-
-        if name:
-            guid = self._guid_mapping[table_name].get(name, None)
-            if not guid:
-                raise EntityError(f"{name} not found in {table_name}")
-            else:
-                return guid
-        else:
-            return None
 
-    def get_table_of_guid(self, guid):
-        return next(
-            (
-                key
-                for key, value in self._guid_mapping.items()
-                if guid in [guid for guid in value.values()]
-            ),
-            None,
-        )
-
-    def get_table_entity_set_name(self, schema_name=None, logical_name=None):
-        tables = self.get_table_definitions()
-
-        if schema_name:
-            key = "SchemaName"
-            name = schema_name
-        elif logical_name:
-            key = "LogicalName"
-            name = logical_name
-        else:
-            raise ValueError("Please input schema or logical name")
-
-        for entity in tables["value"]:
-            if name == entity[key]:
-                return entity["EntitySetName"]
-        raise EntityError(f"{key} not found for {name}")
-
-
-def is_valid_guid(value: str) -> bool:
-    """Returns True if the value is a valid GUID, otherwise False."""
-    try:
-        uuid_obj = uuid.UUID(value)  # Ensure it's a valid UUID
-        return str(uuid_obj) == value.lower()  # Ensure correct format
-    except ValueError:
-        return False
-
-
-class DataverseTable:
+class DataverseEntity(DataverseBase):
     """Generic class for Dataverse entities"""
 
-    def __init__(self, table_logical_name, table_prefix="prefix_"):
+    def __init__(self, table_logical_name, table_prefix="", client=None, **kwargs):
         """
         Args:
             table_logical_name: The pluralized name of the Dataverse table
             table_prefix: The prefix used for custom table/column names (default: "prefix_")
+            client: Optional DataverseClient instance (will create singleton if not provided)
+            **kwargs: Additional options including suppress_property_generation for testing
         """
-        self.dataverse = DataverseClient()
-        if isinstance(table_logical_name, Enum):
-            table_logical_name = str(table_logical_name)
-        self.logical_name = table_logical_name
-        self.table_prefix = table_prefix
-        self.table_name = table_logical_name.replace(self.table_prefix, "").title()
-        self.col_metadata = self.dataverse.get_table_metadata(self.logical_name)
-        # Filter global choices to only include those relevant to our prefix
-        all_choices = self.dataverse.global_choices
-        prefix_filter = self.table_prefix.rstrip("_")
-        self.choices = {
-            name: options for name, options in all_choices.items() if prefix_filter in name
-        }
-        self.relationships = self.get_relationships()
+        super().__init__(table_logical_name, table_prefix, client)
+        self.client = client or DataverseClient()
 
         self.guid = None
         self.data = {}  # Dictionary to store record fields
+        self._properties_generated = False
 
-        # Auto-generate properties based on metadata
-        self._generate_properties()
+        # Generate properties unless suppressed (useful for testing)
+        if not kwargs.get("suppress_property_generation", False):
+            self._generate_properties()
 
     def _generate_properties(self):
         """Automatically generates properties for all valid columns in the table"""
-        logger.info(f"Generating properties for {self.logical_name}")
-        for column_logical_name, metadata in self.col_metadata.items():
-            # Skip system fields and non-user fields
-            if not column_logical_name.startswith(self.table_prefix):
-                continue
-
-            # File and Virtual columns often have IsValidForCreate/Update = False, so allow them through
-            field_type = metadata.get("AttributeType")
-            if (
-                field_type not in ["File", "Virtual"]
-                and not metadata.get("IsValidForCreate")
-                and not metadata.get("IsValidForUpdate")
-            ):
-                continue
+        if self._properties_generated:
+            return
 
-            # Generate property name by removing prefix
-            if column_logical_name.startswith(self.table_prefix):
-                property_name = column_logical_name.replace(
-                    self.table_prefix, "", 1
-                )  # Remove prefix
-            else:
-                property_name = column_logical_name
-
-            # Determine property type based on field metadata
-            field_type = metadata.get("AttributeType")
-
-            if field_type == "File" or (
-                field_type == "Virtual" and "json" in column_logical_name.lower()
-            ):
-                # This is a file field or virtual file field - check this FIRST
-                logger.info(f"Setting {property_name} as file property")
-                setattr(self.__class__, property_name, self.file_property(column_logical_name))
-            elif column_logical_name in self.relationships:
-                # This is a lookup field
-                logger.info(f"Setting {property_name} as lookup property")
-                setattr(self.__class__, property_name, self.lookup_property(column_logical_name))
-            elif column_logical_name in self.choices:
-                # This is a choice field
-                logger.info(f"Setting {property_name} as choice property")
-                setattr(self.__class__, property_name, self.choice_property(column_logical_name))
-            elif field_type == "DateTime":
-                # This is a date and time field
-                logger.info(f"Setting {property_name} as datetime property")
-                setattr(self.__class__, property_name, self.data_property(column_logical_name))
-            else:
-                # This is a regular data field
-                logger.info(f"Setting {property_name} as data property (fallback)")
-                setattr(self.__class__, property_name, self.data_property(column_logical_name))
-
-    # === Init values ===
-    def get_relationships(self):
-        """Fetches all possible lookups (relationships) for this entity."""
-        result = self.dataverse.relationships
+        logger.info(f"Generating properties for {self.table_logical_name}")
+        try:
+            for column_logical_name, metadata in self.get_table_metadata().items():
+                # Skip system fields and non-user fields
+                if not column_logical_name.startswith(self.table_logical_name_prefix):
+                    continue
+
+                # File and Virtual columns often have IsValidForCreate/Update = False, so allow them through
+                field_type = metadata.get("AttributeType")
+                if (
+                    field_type not in ["File", "Virtual"]
+                    and not metadata.get("IsValidForCreate")
+                    and not metadata.get("IsValidForUpdate")
+                ):
+                    continue
+
+                # Generate property name by removing prefix
+                if column_logical_name.startswith(self.table_logical_name_prefix):
+                    property_name = column_logical_name.replace(
+                        self.table_logical_name_prefix, "", 1
+                    )  # Remove prefix
+                else:
+                    property_name = column_logical_name
+
+                # Determine property type based on field metadata
+                field_type = metadata.get("AttributeType")
+
+                if field_type == "File" or (
+                    field_type == "Virtual" and "json" in column_logical_name.lower()
+                ):
+                    # This is a file field or virtual file field - check this FIRST
+                    logger.info(f"Setting {property_name} as file property")
+                    setattr(self.__class__, property_name, self.file_property(column_logical_name))
+                elif column_logical_name in self.get_table_relationships():
+                    # This is a lookup field
+                    logger.info(f"Setting {property_name} as lookup property")
+                    setattr(
+                        self.__class__, property_name, self.lookup_property(column_logical_name)
+                    )
+                elif column_logical_name in self.filtered_choices:
+                    # This is a choice field
+                    logger.info(f"Setting {property_name} as choice property")
+                    setattr(
+                        self.__class__, property_name, self.choice_property(column_logical_name)
+                    )
+                elif field_type == "DateTime":
+                    # This is a date and time field
+                    logger.info(f"Setting {property_name} as datetime property")
+                    setattr(self.__class__, property_name, self.data_property(column_logical_name))
+                else:
+                    # This is a regular data field
+                    logger.info(f"Setting {property_name} as data property (fallback)")
+                    setattr(self.__class__, property_name, self.data_property(column_logical_name))
 
-        _relationships = {}
-        for rel in result.get("value", []):
-            if rel.get("ReferencingEntity") == self.logical_name:
-                # Store lookup column name -> related entity table
-                if "ReferencingAttribute" in rel and "ReferencedEntity" in rel:
-                    _relationships[rel["ReferencingAttribute"]] = rel["ReferencedEntity"]
-        return _relationships
+            self._properties_generated = True
+            logger.info(f"Property generation completed for {self.table_logical_name}")
+        except Exception as e:
+            logger.warning(f"Property generation failed for {self.table_logical_name}: {e}")
+            # Don't raise the exception - entity should still be usable without dynamic properties
 
     # === FREE TEXT COLUMNS ===
     def set_data(self, column, value):
@@ -723,17 +753,17 @@ class DataverseTable:
     def get_data(self, column):
         value = self.data.get(column, "")
 
-        # If value is empty but we have a GUID, try to fetch from Dataverse
+        # If value is empty, but we have a GUID, try to fetch from Dataverse
         if not value and self.guid:
             try:
-                entity_set_name = self.dataverse.get_table_entity_set_name(
-                    logical_name=self.logical_name
+                entity_set_name = self.get_table_entity_set_name(
+                    logical_name=self.table_logical_name
                 )
-                record = self.dataverse.get_record(entity_set_name, self.guid)
+                record = self.get_record(entity_set_name, self.guid)
 
                 # Update our data with the fresh record
                 for field, fresh_value in record.items():
-                    if field.startswith(self.table_prefix) or field.endswith("id"):
+                    if field.startswith(self.table_logical_name_prefix) or field.endswith("id"):
                         self.data[field] = fresh_value
 
                 # Return the requested value
@@ -757,23 +787,37 @@ class DataverseTable:
             return False
 
         try:
-            entity_set_name = self.dataverse.get_table_entity_set_name(
-                logical_name=self.logical_name
-            )
-            record = self.dataverse.get_record(entity_set_name, self.guid)
+            entity_set_name = self.get_table_entity_set_name(logical_name=self.table_logical_name)
+            record = self.get_record(entity_set_name, self.guid)
 
             # Update our data with the fresh record
             for field, fresh_value in record.items():
-                if field.startswith(self.table_prefix) or field.endswith("id"):
+                if field.startswith(self.table_logical_name_prefix) or field.endswith("id"):
                     self.data[field] = fresh_value
 
-            logger.info(f"Refreshed data for {self.logical_name} GUID: {self.guid}")
+            logger.info(f"Refreshed data for {self.table_logical_name} GUID: {self.guid}")
             return True
 
         except Exception as e:
-            logger.error(f"Failed to refresh data for {self.logical_name} GUID {self.guid}: {e}")
+            logger.error(
+                f"Failed to refresh data for {self.table_logical_name} GUID {self.guid}: {e}"
+            )
             return False
 
+    def fetch_data(self, entity_id=None):
+        """
+        Fetch data for an existing entity from Dataverse by its ID.
+
+        Args:
+            entity_id: The GUID of the entity to fetch
+
+        Returns:
+            bool: True if fetch was successful, False otherwise
+        """
+        if entity_id is not None:
+            self.guid = entity_id
+        return self.refresh()
+
     @staticmethod
     def data_property(column):
         def getter(self):
@@ -787,15 +831,15 @@ class DataverseTable:
     # === LOOKUP
     def set_lookup(self, lookup_column, value: str):
         """Adds a lookup reference using @odata.bind"""
-        lookup_column_schema_name = self.col_metadata[lookup_column]["SchemaName"]
+        lookup_column_schema_name = self.get_table_metadata()[lookup_column]["SchemaName"]
 
-        target_entity = self.relationships.get(lookup_column)  # Get table of lookup column
-        target_entity_set_name = self.dataverse.get_table_entity_set_name(
-            logical_name=target_entity
-        )
+        target_entity = self.get_table_relationships().get(
+            lookup_column
+        )  # Get table of lookup column
+        target_entity_set_name = self.get_table_entity_set_name(logical_name=target_entity)
 
         if not is_valid_guid(value):
-            value = self.dataverse.name_to_guid(target_entity, value)
+            value = self.name_to_guid(target_entity, value)
 
         self.data[f"{lookup_column_schema_name}@odata.bind"] = f"/{target_entity_set_name}({value})"
 
@@ -819,7 +863,7 @@ class DataverseTable:
     # === CHOICE
     def set_choice(self, column, value):
         """Adds a choice field by looking up its numeric value"""
-        choice_value = self.choices[column].get(value)
+        choice_value = self.filtered_choices[column].get(value)  # Get numeric value for choice
         if choice_value is not None:
             self.data[column] = choice_value
         else:
@@ -829,7 +873,10 @@ class DataverseTable:
 
     def get_choice(self, column):
         """Retrieves the readable choice name from its stored numeric value (Int → String)"""
-        return self.choices.get(column, {}).get(self.data.get(column), None)
+        choice_dict = self.filtered_choices.get(column, {})
+        choices_invert = {v: k for k, v in choice_dict.items()}  # Invert dict for reverse lookup
+        numeric_value = self.data.get(column, None)
+        return choices_invert.get(numeric_value, None)
 
     @staticmethod
     def choice_property(lookup_column):
@@ -844,11 +891,11 @@ class DataverseTable:
         if not self.guid:
             raise EntityError("Record must be created first (GUID required)")
 
-        entity_set_name = self.dataverse.get_table_entity_set_name(logical_name=self.logical_name)
-        base_url = f"{self.dataverse.environment_uri}api/data/v9.2/{entity_set_name}({self.guid})"
+        entity_set_name = self.get_table_entity_set_name(logical_name=self.table_logical_name)
+        base_url = f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}({self.guid})"
 
         # Step 1: PATCH metadata
-        meta_headers = self.dataverse.session.headers.copy()
+        meta_headers = self.client.session.headers.copy()
         meta_headers["Content-Type"] = "application/json"
 
         metadata_payload = {
@@ -915,18 +962,18 @@ class DataverseTable:
         if not self.guid:
             return None
 
-        entity_set_name = self.dataverse.get_table_entity_set_name(logical_name=self.logical_name)
-        return f"{self.dataverse.environment_uri}api/data/v9.2/{entity_set_name}({self.guid})/{column}/$value"
+        entity_set_name = self.get_table_entity_set_name(logical_name=self.table_logical_name)
+        return f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}({self.guid})/{column}/$value"
 
     def get_file(self, column):
         """Downloads and returns file content from file columns"""
         if not self.guid:
             return None
 
-        entity_set_name = self.dataverse.get_table_entity_set_name(logical_name=self.logical_name)
-        file_url = f"{self.dataverse.environment_uri}api/data/v9.2/{entity_set_name}({self.guid})/{column}/$value"
+        entity_set_name = self.get_table_entity_set_name(logical_name=self.table_logical_name)
+        file_url = f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}({self.guid})/{column}/$value"
 
-        response = self.dataverse.session.get(file_url)
+        response = self.client.session.get(file_url)
 
         if response.status_code == 200:
             # For JSON files, try to parse and return as dict
@@ -963,12 +1010,12 @@ class DataverseTable:
                 validated_data[field] = value
                 continue
 
-            if field not in self.col_metadata:
+            if field not in self.get_table_metadata():
                 # Field not in metadata, pass through as-is
                 validated_data[field] = value
                 continue
 
-            field_type = self.col_metadata[field].get("AttributeType")
+            field_type = self.get_table_metadata()[field].get("AttributeType")
 
             if field_type == "Decimal" and isinstance(value, (int, float, str)):
                 # Convert to proper decimal format for Dataverse
@@ -999,24 +1046,40 @@ class DataverseTable:
         if self.guid:
             return self._update_record()
 
-        # === CHECK IF ROW EXISTS (for certain table types there is a casual name identifier) ===
-        if self.logical_name in [f"{self.table_prefix}article", f"{self.table_prefix}recipe"]:
-            # Check if name exists
-            guid = self.dataverse.get_guid_by_casual_name(self.logical_name, self.data)
-            if guid:
-                self.guid = guid
-                logger.warning(
-                    f"✅ This {self.logical_name} already exists. GUID {guid} fetched and stored, no data written."
+        # === OPTIONAL DUPLICATE CHECK (warn if potential name-based duplicate exists) ===
+        name_columns = [col for col in self.data.keys() if "name" in col.lower()]
+        if name_columns:
+            try:
+                # Simple check for existing record with same name (warning only)
+                name_column = name_columns[0]
+                name_value = self.data[name_column]
+                guid_column = self.table_logical_name + "id"
+
+                entity_set_name = self.get_table_entity_set_name(
+                    logical_name=self.table_logical_name
                 )
-                return guid
+                request_uri = f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}?$select={name_column},{guid_column}&$filter={name_column} eq '{name_value}'"
+
+                response = self.client.session.get(request_uri)
+                if response.status_code == 200:
+                    records = response.json().get("value", [])
+                    if records:
+                        existing_guid = records[0].get(guid_column)
+                        logger.warning(
+                            f"⚠️  Record with name '{name_value}' may already exist in {self.table_logical_name}. "
+                            f"Existing GUID: {existing_guid}. Creating new record anyway."
+                        )
+            except Exception as e:
+                # If duplicate check fails, just continue with creation
+                logger.info(f"Duplicate check skipped due to error: {e}")
 
         # This is a CREATE operation
         return self._create_record()
 
-    def _create_record(self):
+    def _create_record(self) -> uuid.UUID | None:
         """Creates a new record in Dataverse"""
-        entity_set_name = self.dataverse.get_table_entity_set_name(logical_name=self.logical_name)
-        request_uri = f"{self.dataverse.environment_uri}api/data/v9.2/{entity_set_name}"
+        entity_set_name = self.get_table_entity_set_name(logical_name=self.table_logical_name)
+        request_uri = f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}"
 
         # Validate and convert data types before sending
         validated_data = self._validate_and_convert_data(self.data)
@@ -1030,12 +1093,12 @@ class DataverseTable:
             "POST",
             request_uri,
             data=record_json,
-            headers={**self.dataverse.session.headers, "Content-Type": "application/json"},
+            headers={**self.client.session.headers, "Content-Type": "application/json"},
         ).prepare()
-        response = self.dataverse.session.send(req)
+        response = self.client.session.send(req)
 
         if response.status_code == 204:
-            logger.info(f"✅ Record created in {self.logical_name} successfully!")
+            logger.info(f"✅ Record created in {self.table_logical_name} successfully!")
 
             # Extract GUID from OData-EntityId header
             created_record_url = response.headers.get("OData-EntityId")
@@ -1044,19 +1107,21 @@ class DataverseTable:
                 logger.info(f"🆔 Assigned GUID: {self.guid}")
 
                 # Update guid mapping
-                self.dataverse.name_to_guid(self.logical_name)
+                self.name_to_guid(self.table_logical_name)
                 return self.guid
+            return None
         else:
             # Enhanced error message with field information
-            error_details = []
-            error_details.append(f"Table: {entity_set_name}")
-            error_details.append(f"Record data sent: {json.dumps(record, indent=2)}")
+            error_details = [
+                f"Table: {entity_set_name}",
+                f"Record data sent: {json.dumps(record, indent=2)}",
+            ]
 
             # Analyze data types for decimal conversion issues
             decimal_fields = []
             for field, value in record.items():
-                if isinstance(value, (int, float)) and field in self.col_metadata:
-                    field_type = self.col_metadata[field].get("AttributeType")
+                if isinstance(value, (int, float)) and field in self.get_table_metadata():
+                    field_type = self.get_table_metadata()[field].get("AttributeType")
                     if field_type == "Decimal":
                         decimal_fields.append(
                             f"  {field}: {value} (type: {type(value).__name__}, expected: Decimal)"
@@ -1075,10 +1140,8 @@ class DataverseTable:
 
     def _update_record(self):
         """Updates an existing record in Dataverse"""
-        entity_set_name = self.dataverse.get_table_entity_set_name(logical_name=self.logical_name)
-        request_uri = (
-            f"{self.dataverse.environment_uri}api/data/v9.2/{entity_set_name}({self.guid})"
-        )
+        entity_set_name = self.get_table_entity_set_name(logical_name=self.table_logical_name)
+        request_uri = f"{self.client.environment_uri}api/data/v9.2/{entity_set_name}({self.guid})"
 
         # Validate and convert data types before sending
         validated_data = self._validate_and_convert_data(self.data)
@@ -1094,7 +1157,7 @@ class DataverseTable:
                 update_data[field] = value
 
         if not update_data:
-            logger.info(f"No data to update for {self.logical_name} GUID: {self.guid}")
+            logger.info(f"No data to update for {self.table_logical_name} GUID: {self.guid}")
             return self.guid
 
         # Send update to Dataverse (convert Decimals to floats)
@@ -1103,12 +1166,12 @@ class DataverseTable:
             "PATCH",
             request_uri,
             data=update_json,
-            headers={**self.dataverse.session.headers, "Content-Type": "application/json"},
+            headers={**self.client.session.headers, "Content-Type": "application/json"},
         ).prepare()
-        response = self.dataverse.session.send(req)
+        response = self.client.session.send(req)
 
         if response.status_code == 204:
-            logger.info(f"✅ Record updated in {self.logical_name} successfully!")
+            logger.info(f"✅ Record updated in {self.table_logical_name} successfully!")
             return self.guid
         else:
             error_msg = f"Error updating record in {entity_set_name}: {response.text}"