GeneralManager 0.7.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

general_manager/interface/databaseBasedInterface.py

@@ -1,12 +1,5 @@
 from __future__ import annotations
-from typing import (
-    Type,
-    ClassVar,
-    Any,
-    Callable,
-    TYPE_CHECKING,
-    TypeVar,
-)
+from typing import Type, ClassVar, Any, Callable, TYPE_CHECKING, TypeVar, Generic
 from django.db import models
 from django.conf import settings
 from datetime import datetime, timedelta
@@ -30,6 +23,11 @@ from general_manager.interface.baseInterface import (
 )
 from general_manager.manager.input import Input
 from general_manager.bucket.databaseBucket import DatabaseBucket
+from general_manager.interface.models import (
+    GeneralManagerBasisModel,
+    GeneralManagerModel,
+    getFullCleanMethode,
+)
 
 if TYPE_CHECKING:
     from general_manager.manager.generalManager import GeneralManager
@@ -39,69 +37,11 @@ if TYPE_CHECKING:
 modelsModel = TypeVar("modelsModel", bound=models.Model)
 
 
-def getFullCleanMethode(model: Type[models.Model]) -> Callable[..., None]:
-    """
-    Generates a custom `full_clean` method for a Django model that combines standard validation with additional rule-based checks.
-
-    The returned method first performs Django's built-in model validation, then evaluates any custom rules defined in the model's `_meta.rules` attribute. If any validation or rule fails, a `ValidationError` is raised containing all collected errors.
-    """
-
-    def full_clean(self: models.Model, *args: Any, **kwargs: Any):
-        errors: dict[str, Any] = {}
-        try:
-            super(model, self).full_clean(*args, **kwargs)  # type: ignore
-        except ValidationError as e:
-            errors.update(e.message_dict)
-
-        rules: list[Rule] = getattr(self._meta, "rules")
-        for rule in rules:
-            if not rule.evaluate(self):
-                error_message = rule.getErrorMessage()
-                if error_message:
-                    errors.update(error_message)
-
-        if errors:
-            raise ValidationError(errors)
-
-    return full_clean
+MODEL_TYPE = TypeVar("MODEL_TYPE", bound=GeneralManagerBasisModel)
 
 
-class GeneralManagerBasisModel(models.Model):
-    _general_manager_class: ClassVar[Type[GeneralManager]]
-    is_active = models.BooleanField(default=True)
-    history = HistoricalRecords(inherit=True)
-
-    class Meta:
-        abstract = True
-
-
-class GeneralManagerModel(GeneralManagerBasisModel):
-    changed_by = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT)
-    changed_by_id: int
-
-    @property
-    def _history_user(self) -> AbstractUser:
-        """
-        Returns the user who last modified this model instance.
-        """
-        return self.changed_by
-
-    @_history_user.setter
-    def _history_user(self, value: AbstractUser) -> None:
-        """
-        Sets the user responsible for the latest change to the model instance.
-
-        Args:
-            value: The user to associate with the change.
-        """
-        self.changed_by = value
-
-    class Meta:  # type: ignore
-        abstract = True
-
-
-class DBBasedInterface(InterfaceBase):
-    _model: Type[GeneralManagerBasisModel]
+class DBBasedInterface(InterfaceBase, Generic[MODEL_TYPE]):
+    _model: Type[MODEL_TYPE]
     input_fields: dict[str, Input] = {"id": Input(int)}
 
     def __init__(
@@ -111,9 +51,9 @@ class DBBasedInterface(InterfaceBase):
         **kwargs: dict[str, Any],
     ):
         """
-        Initializes the interface instance and loads the corresponding model record.
-
-        If a `search_date` is provided, retrieves the historical record as of that date; otherwise, loads the current record.
+        Initialize the interface and load the associated model instance.
+        
+        If `search_date` is provided, loads the historical record as of that date; otherwise, loads the current record.
         """
         super().__init__(*args, **kwargs)
         self.pk = self.identification["id"]
@@ -200,9 +140,12 @@ class DBBasedInterface(InterfaceBase):
     @classmethod
     def getAttributeTypes(cls) -> dict[str, AttributeTypedDict]:
         """
-        Returns a dictionary mapping attribute names to their type information and metadata.
-
-        The returned dictionary includes all model fields, custom fields, foreign keys, many-to-many, and reverse relation fields. Each entry provides the Python type (translated from Django field types when possible), whether the field is required, editable, and its default value. For related models that have a general manager class, the type is set to that class.
+        Return a dictionary mapping attribute names to metadata describing their types and properties.
+        
+        The dictionary includes all model fields, custom fields, foreign keys, many-to-many, and reverse relation fields. For each attribute, the metadata specifies its Python type (translated from Django field types when possible), whether it is required, editable, derived, and its default value. For related models with a general manager class, the type is set to that class.
+        
+        Returns:
+            dict[str, AttributeTypedDict]: Mapping of attribute names to their type information and metadata.
         """
         TRANSLATION: dict[Type[models.Field[Any, Any]], type] = {
             models.fields.BigAutoField: int,
@@ -228,6 +171,7 @@ class DBBasedInterface(InterfaceBase):
             field: models.Field = getattr(cls._model, field_name)
             fields[field_name] = {
                 "type": type(field),
+                "is_derived": False,
                 "is_required": not field.null,
                 "is_editable": field.editable,
                 "default": field.default,
@@ -238,6 +182,7 @@ class DBBasedInterface(InterfaceBase):
                 field: models.Field = getattr(cls._model, field_name).field
                 fields[field_name] = {
                     "type": type(field),
+                    "is_derived": False,
                     "is_required": not field.null,
                     "is_editable": field.editable,
                     "default": field.default,
@@ -255,6 +200,7 @@ class DBBasedInterface(InterfaceBase):
             elif related_model is not None:
                 fields[field_name] = {
                     "type": related_model,
+                    "is_derived": False,
                     "is_required": not field.null,
                     "is_editable": field.editable,
                     "default": field.default,
@@ -280,6 +226,7 @@ class DBBasedInterface(InterfaceBase):
                 fields[f"{field_name}_list"] = {
                     "type": related_model,
                     "is_required": False,
+                    "is_derived": not bool(field.many_to_many),
                     "is_editable": bool(field.many_to_many and field.editable),
                     "default": None,
                 }
@@ -453,9 +400,9 @@ class DBBasedInterface(InterfaceBase):
     ) -> tuple[attributes, interfaceBaseClass, relatedClass]:
         # Felder aus der Interface-Klasse sammeln
         """
-        Dynamically creates a Django model class, its associated interface class, and a factory class based on the provided interface definition.
+        Dynamically generates a Django model class, its associated interface class, and a factory class from an interface definition.
         
-        This method extracts fields and meta information from the interface class, constructs a new Django model inheriting from the specified base model class, attaches custom validation rules if present, and generates corresponding interface and factory classes. The resulting classes are returned for integration into the general manager framework.
+        This method collects fields and metadata from the provided interface class, creates a new Django model inheriting from the specified base model class, attaches custom validation rules if present, and constructs corresponding interface and factory classes. The updated attributes dictionary, the new interface class, and the newly created model class are returned for integration into the general manager framework.
         
         Parameters:
             name: The name for the dynamically created model class.
@@ -464,7 +411,7 @@ class DBBasedInterface(InterfaceBase):
             base_model_class: The base class to use for the new model (defaults to GeneralManagerModel).
         
         Returns:
-            A tuple containing the updated attributes dictionary, the new interface class, and the newly created model class.
+            tuple: A tuple containing the updated attributes dictionary, the new interface class, and the newly created model class.
         """
         model_fields: dict[str, Any] = {}
         meta_class = None

general_manager/interface/databaseInterface.py

@@ -11,14 +11,25 @@ from general_manager.interface.databaseBasedInterface import (
 )
 
 
-class DatabaseInterface(DBBasedInterface):
+class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
     _interface_type = "database"
 
     @classmethod
     def create(
-        cls, creator_id: int, history_comment: str | None = None, **kwargs: Any
+        cls, creator_id: int | None, history_comment: str | None = None, **kwargs: Any
     ) -> int:
+        """
+        Create a new model instance with the provided attributes and optional history tracking.
+
+        Validates input attributes, separates and sets many-to-many relationships, saves the instance with optional creator and history comment, and returns the primary key of the created instance.
+
+        Parameters:
+            creator_id (int | None): The ID of the user creating the instance, or None if not applicable.
+            history_comment (str | None): Optional comment to record in the instance's history.
 
+        Returns:
+            int: The primary key of the newly created instance.
+        """
         cls._checkForInvalidKwargs(cls._model, kwargs=kwargs)
         kwargs, many_to_many_kwargs = cls._sortKwargs(cls._model, kwargs)
         instance = cls.__setAttrForWrite(cls._model(), kwargs)
@@ -27,9 +38,18 @@ class DatabaseInterface(DBBasedInterface):
         return pk
 
     def update(
-        self, creator_id: int, history_comment: str | None = None, **kwargs: Any
+        self, creator_id: int | None, history_comment: str | None = None, **kwargs: Any
     ) -> int:
+        """
+        Update the current model instance with new attribute values and many-to-many relationships, saving changes with optional history tracking.
+
+        Parameters:
+            creator_id (int | None): The ID of the user making the update, or None if not specified.
+            history_comment (str | None): An optional comment describing the reason for the update.
 
+        Returns:
+            int: The primary key of the updated instance.
+        """
         self._checkForInvalidKwargs(self._model, kwargs=kwargs)
         kwargs, many_to_many_kwargs = self._sortKwargs(self._model, kwargs)
         instance = self.__setAttrForWrite(self._model.objects.get(pk=self.pk), kwargs)
@@ -37,7 +57,19 @@ class DatabaseInterface(DBBasedInterface):
         self.__setManyToManyAttributes(instance, many_to_many_kwargs)
         return pk
 
-    def deactivate(self, creator_id: int, history_comment: str | None = None) -> int:
+    def deactivate(
+        self, creator_id: int | None, history_comment: str | None = None
+    ) -> int:
+        """
+        Deactivate the current model instance by setting its `is_active` flag to `False` and recording the change with an optional history comment.
+
+        Parameters:
+            creator_id (int | None): The ID of the user performing the deactivation, or None if not specified.
+            history_comment (str | None): An optional comment to include in the instance's history log.
+
+        Returns:
+            int: The primary key of the deactivated instance.
+        """
         instance = self._model.objects.get(pk=self.pk)
         instance.is_active = False
         if history_comment:
@@ -79,7 +111,12 @@ class DatabaseInterface(DBBasedInterface):
             if isinstance(value, GeneralManager):
                 value = value.identification["id"]
                 key = f"{key}_id"
-            setattr(instance, key, value)
+            try:
+                setattr(instance, key, value)
+            except ValueError as e:
+                raise ValueError(f"Invalid value for {key}: {value}") from e
+            except TypeError as e:
+                raise TypeError(f"Type error for {key}: {e}") from e
         return instance
 
     @staticmethod
@@ -89,7 +126,7 @@ class DatabaseInterface(DBBasedInterface):
         for key in kwargs:
             temp_key = key.split("_id_list")[0]  # Remove '_id_list' suffix
             if temp_key not in attributes and temp_key not in field_names:
-                raise ValueError(f"{key} does not exsist in {model.__name__}")
+                raise ValueError(f"{key} does not exist in {model.__name__}")
 
     @staticmethod
     def _sortKwargs(
@@ -106,17 +143,15 @@ class DatabaseInterface(DBBasedInterface):
     @classmethod
     @transaction.atomic
     def _save_with_history(
-        cls, instance: GeneralManagerModel, creator_id: int, history_comment: str | None
+        cls,
+        instance: GeneralManagerModel,
+        creator_id: int | None,
+        history_comment: str | None,
     ) -> int:
         """
-        Saves a model instance with validation and optional history tracking.
+        Atomically saves a model instance with validation and optional history comment.
 
-        Sets the `changed_by_id` field, validates the instance, applies a history comment if provided, and saves the instance within an atomic transaction.
-
-        Args:
-            instance: The model instance to save.
-            creator_id: The ID of the user making the change.
-            history_comment: Optional comment describing the reason for the change.
+        Sets the `changed_by_id` field, validates the instance, applies a history comment if provided, and saves the instance within a database transaction.
 
         Returns:
             The primary key of the saved instance.

general_manager/interface/models.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+from typing import Type, ClassVar, Any, Callable, TYPE_CHECKING, TypeVar
+from django.db import models
+from django.conf import settings
+from simple_history.models import HistoricalRecords  # type: ignore
+from django.core.exceptions import ValidationError
+
+
+if TYPE_CHECKING:
+    from general_manager.manager.generalManager import GeneralManager
+    from django.contrib.auth.models import AbstractUser
+    from general_manager.rule.rule import Rule
+
+modelsModel = TypeVar("modelsModel", bound=models.Model)
+
+
+def getFullCleanMethode(model: Type[models.Model]) -> Callable[..., None]:
+    """
+    Return a custom `full_clean` method for a Django model that performs both standard validation and additional rule-based checks.
+    
+    The generated method first applies Django's built-in model validation, then evaluates custom rules defined in the model's `_meta.rules` attribute. If any validation or rule fails, it raises a `ValidationError` containing all collected errors.
+    
+    Parameters:
+        model (Type[models.Model]): The Django model class for which to generate the custom `full_clean` method.
+    
+    Returns:
+        Callable[..., None]: A `full_clean` method that can be assigned to the model class.
+    """
+
+    def full_clean(self: models.Model, *args: Any, **kwargs: Any):
+        """
+        Performs full validation on the model instance, including both standard Django validation and custom rule-based checks.
+        
+        Aggregates errors from Django's built-in validation and any additional rules defined in the model's `_meta.rules` attribute. Raises a `ValidationError` containing all collected errors if any validation or rule check fails.
+        """
+        errors: dict[str, Any] = {}
+        try:
+            super(model, self).full_clean(*args, **kwargs)  # type: ignore
+        except ValidationError as e:
+            errors.update(e.message_dict)
+
+        rules: list[Rule] = getattr(self._meta, "rules")
+        for rule in rules:
+            if not rule.evaluate(self):
+                error_message = rule.getErrorMessage()
+                if error_message:
+                    errors.update(error_message)
+
+        if errors:
+            raise ValidationError(errors)
+
+    return full_clean
+
+
+class GeneralManagerBasisModel(models.Model):
+    _general_manager_class: ClassVar[Type[GeneralManager]]
+    is_active = models.BooleanField(default=True)
+    history = HistoricalRecords(inherit=True)
+
+    class Meta:
+        abstract = True
+
+
+class GeneralManagerModel(GeneralManagerBasisModel):
+    changed_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL, on_delete=models.PROTECT, null=True, blank=True
+    )
+    changed_by_id: int | None
+
+    @property
+    def _history_user(self) -> AbstractUser | None:
+        """
+        Returns the user who last modified this model instance, or None if no user is set.
+        """
+        return self.changed_by
+
+    @_history_user.setter
+    def _history_user(self, value: AbstractUser) -> None:
+        """
+        Set the user responsible for the most recent change to the model instance.
+        
+        Parameters:
+            value (AbstractUser): The user to associate with the latest modification.
+        """
+        self.changed_by = value
+
+    class Meta:  # type: ignore
+        abstract = True

general_manager/interface/readOnlyInterface.py

@@ -24,17 +24,16 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class ReadOnlyInterface(DBBasedInterface):
+class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
     _interface_type = "readonly"
-    _model: Type[GeneralManagerBasisModel]
     _parent_class: Type[GeneralManager]
 
     @staticmethod
     def getUniqueFields(model: Type[models.Model]) -> set[str]:
         """
-        Return the set of field names that uniquely identify instances of the given Django model.
+        Return a set of field names that uniquely identify instances of the specified Django model.
         
-        Considers fields marked as unique (excluding "id"), unique_together constraints, and UniqueConstraint definitions.
+        Considers fields marked as unique (excluding "id"), as well as fields defined in `unique_together` and `UniqueConstraint` constraints.
         """
         opts = model._meta
         unique_fields: set[str] = set()
@@ -57,9 +56,9 @@ class ReadOnlyInterface(DBBasedInterface):
     @classmethod
     def syncData(cls) -> None:
         """
-        Synchronizes the associated Django model with the JSON data from the parent class, ensuring records match exactly.
+        Synchronizes the associated Django model with JSON data from the parent class, ensuring the database records match the provided data exactly.
         
-        Parses the JSON data, creates or updates model instances based on unique fields, and marks as inactive any database records not present in the JSON data. Raises a ValueError if required attributes are missing, if the JSON data is invalid, or if no unique fields are defined.
+        Parses the JSON data, creates or updates model instances based on unique fields, and deactivates any database records not present in the JSON data. Raises a ValueError if required attributes are missing, if the JSON data is invalid, or if no unique fields are defined.
         """
         if cls.ensureSchemaIsUpToDate(cls._parent_class, cls._model):
             logger.warning(
@@ -138,22 +137,18 @@ class ReadOnlyInterface(DBBasedInterface):
         new_manager_class: Type[GeneralManager], model: Type[models.Model]
     ) -> list[Warning]:
         """
-        Checks whether the database schema for the given model matches the model definition.
-        
-        Parameters:
-            new_manager_class (Type[GeneralManager]): The manager class associated with the model.
-            model (Type[models.Model]): The Django model to check.
+        Check if the database schema for a Django model matches its model definition.
         
         Returns:
-            list[Warning]: A list of Django Warning objects describing schema issues, or an empty list if the schema is up to date.
+            A list of Django Warning objects describing schema issues, such as missing tables or column mismatches. Returns an empty list if the schema is up to date.
         """
 
         def table_exists(table_name: str) -> bool:
             """
-            Check if a database table with the given name exists.
+            Determine whether a database table with the specified name exists.
             
             Parameters:
-                table_name (str): The name of the database table to check.
+                table_name (str): Name of the database table to check.
             
             Returns:
                 bool: True if the table exists, False otherwise.
@@ -166,11 +161,12 @@ class ReadOnlyInterface(DBBasedInterface):
             model: Type[models.Model], table: str
         ) -> tuple[list[str], list[str]]:
             """
-            Compare a Django model's fields to the columns of a database table.
+            Compares the fields of a Django model to the columns of a specified database table.
             
             Returns:
-                missing (list[str]): Columns defined in the model but missing from the database table.
-                extra (list[str]): Columns present in the database table but not defined in the model.
+                A tuple containing two lists:
+                    - The first list contains column names defined in the model but missing from the database table.
+                    - The second list contains column names present in the database table but not defined in the model.
             """
             with connection.cursor() as cursor:
                 desc = connection.introspection.get_table_description(cursor, table)
@@ -208,7 +204,7 @@ class ReadOnlyInterface(DBBasedInterface):
         """
         Decorator for post-creation hooks that registers a new manager class as read-only.
         
-        After executing the wrapped post-creation function, this decorator appends the newly created manager class to the `read_only_classes` list in the meta-class, marking it as a read-only interface.
+        After the wrapped post-creation function is executed, the newly created manager class is added to the meta-class's list of read-only classes, marking it as a read-only interface.
         """
 
         def wrapper(
@@ -217,12 +213,9 @@ class ReadOnlyInterface(DBBasedInterface):
             model: Type[GeneralManagerBasisModel],
         ):
             """
-            Registers the newly created class as a read-only class after invoking the wrapped post-creation function.
+            Registers a newly created manager class as read-only after executing the wrapped post-creation function.
             
-            Parameters:
-                new_class (Type[GeneralManager]): The newly created manager class to register.
-                interface_cls (Type[ReadOnlyInterface]): The associated read-only interface class.
-                model (Type[GeneralManagerModel]): The model class associated with the manager.
+            This function appends the new manager class to the list of read-only classes in the meta system, ensuring it is recognized as a read-only interface.
             """
             from general_manager.manager.meta import GeneralManagerMeta
 
@@ -234,16 +227,28 @@ class ReadOnlyInterface(DBBasedInterface):
     @staticmethod
     def readOnlyPreCreate(func: Callable[..., Any]) -> Callable[..., Any]:
         """
-        Decorator for pre-creation hook functions to ensure the base model class is set to ReadOnlyModel.
+        Decorator for pre-creation hook functions that ensures the base model class is set to `GeneralManagerBasisModel`.
         
-        Wraps a pre-creation function, injecting ReadOnlyModel as the base model class argument before the GeneralManager instance is created.
+        Wraps a pre-creation function, injecting `GeneralManagerBasisModel` as the `base_model_class` argument before the manager class is created.
         """
+
         def wrapper(
             name: generalManagerClassName,
             attrs: attributes,
             interface: interfaceBaseClass,
             base_model_class=GeneralManagerBasisModel,
         ):
+            """
+            Wraps a function to ensure the `base_model_class` argument is set to `GeneralManagerBasisModel` before invocation.
+            
+            Parameters:
+                name: The name of the manager class being created.
+                attrs: Attributes for the manager class.
+                interface: The interface base class to use.
+            
+            Returns:
+                The result of calling the wrapped function with `base_model_class` set to `GeneralManagerBasisModel`.
+            """
             return func(
                 name, attrs, interface, base_model_class=GeneralManagerBasisModel
             )
@@ -253,12 +258,14 @@ class ReadOnlyInterface(DBBasedInterface):
     @classmethod
     def handleInterface(cls) -> tuple[classPreCreationMethod, classPostCreationMethod]:
         """
-        Return the pre- and post-creation hook methods for integrating this interface with a GeneralManager.
+        Return the pre- and post-creation hook methods for integrating the interface with a manager meta-class system.
         
-        The returned tuple contains the pre-creation method, which injects the base model class, and the post-creation method, which registers the class as read-only. These hooks are intended for use by GeneralManagerMeta during the manager class lifecycle.
+        The returned tuple includes:
+        - A pre-creation method that ensures the base model class is set for read-only operation.
+        - A post-creation method that registers the manager class as read-only.
         
         Returns:
-            tuple: A pair of methods for pre- and post-creation processing.
+            tuple: The pre-creation and post-creation hook methods for manager class lifecycle integration.
         """
         return cls.readOnlyPreCreate(cls._preCreate), cls.readOnlyPostCreate(
             cls._postCreate