GeneralManager 0.19.2__py3-none-any.whl → 0.20.1__py3-none-any.whl

general_manager/interface/read_only_interface.py

@@ -1,28 +1,29 @@
 """Read-only interface that mirrors JSON datasets into Django models."""
 
 from __future__ import annotations
+
 import json
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Type, cast
+
+from django.core.checks import Warning
+from django.db import connection, models, transaction, IntegrityError
 
-from typing import Type, Any, Callable, TYPE_CHECKING, cast, ClassVar
-from django.db import models, transaction
 from general_manager.interface.database_based_interface import (
     DBBasedInterface,
     GeneralManagerBasisModel,
-    classPreCreationMethod,
+    attributes,
     classPostCreationMethod,
+    classPreCreationMethod,
     generalManagerClassName,
-    attributes,
     interfaceBaseClass,
 )
-from django.db import connection
-from django.core.checks import Warning
-import logging
+from general_manager.logging import get_logger
 
 if TYPE_CHECKING:
     from general_manager.manager.general_manager import GeneralManager
 
 
-logger = logging.getLogger(__name__)
+logger = get_logger("interface.read_only")
 
 
 class MissingReadOnlyDataError(ValueError):
@@ -131,7 +132,11 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
         """
         if cls.ensure_schema_is_up_to_date(cls._parent_class, cls._model):
             logger.warning(
-                f"Schema for ReadOnlyInterface '{cls._parent_class.__name__}' is not up to date."
+                "readonly schema out of date",
+                context={
+                    "manager": cls._parent_class.__name__,
+                    "model": cls._model.__name__,
+                },
             )
             return
 
@@ -154,6 +159,7 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
         data_list = cast(list[dict[str, Any]], parsed_data)
 
         unique_fields = cls.get_unique_fields(model)
+        unique_field_order = tuple(sorted(unique_fields))
         if not unique_fields:
             raise MissingUniqueFieldError(parent_class.__name__)
 
@@ -163,29 +169,43 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
             "deactivated": [],
         }
 
+        editable_fields = {
+            f.name
+            for f in model._meta.local_fields
+            if getattr(f, "editable", True) and not getattr(f, "primary_key", False)
+        } - {"is_active"}
+
         with transaction.atomic():
-            json_unique_values: set[Any] = set()
+            json_unique_values: set[tuple[Any, ...]] = set()
 
             # data synchronization
             for idx, data in enumerate(data_list):
                 try:
-                    lookup = {field: data[field] for field in unique_fields}
+                    lookup = {field: data[field] for field in unique_field_order}
                 except KeyError as e:
                     missing = e.args[0]
                     raise InvalidReadOnlyDataFormatError() from KeyError(
                         f"Item {idx} missing unique field '{missing}'."
                     )
-                unique_identifier = tuple(lookup[field] for field in unique_fields)
+                unique_identifier = tuple(lookup[field] for field in unique_field_order)
                 json_unique_values.add(unique_identifier)
-
-                instance, is_created = model.objects.get_or_create(**lookup)
+                instance = model.objects.filter(**lookup).first()
+                is_created = False
+                if instance is None:
+                    # sanitize input and create with race-safety
+                    allowed_fields = {f.name for f in model._meta.local_fields}
+                    create_kwargs = {
+                        k: v for k, v in data.items() if k in allowed_fields
+                    }
+                    try:
+                        instance = model.objects.create(**create_kwargs)
+                        is_created = True
+                    except IntegrityError:
+                        # created concurrently — fetch it
+                        instance = model.objects.filter(**lookup).first()
+                        if instance is None:
+                            raise
                 updated = False
-                editable_fields = {
-                    f.name
-                    for f in model._meta.local_fields
-                    if getattr(f, "editable", True)
-                    and not getattr(f, "primary_key", False)
-                } - {"is_active"}
                 for field_name in editable_fields.intersection(data.keys()):
                     value = data[field_name]
                     if getattr(instance, field_name, None) != value:
@@ -199,8 +219,10 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
             # deactivate instances not in JSON data
             existing_instances = model.objects.filter(is_active=True)
             for instance in existing_instances:
-                lookup = {field: getattr(instance, field) for field in unique_fields}
-                unique_identifier = tuple(lookup[field] for field in unique_fields)
+                lookup = {
+                    field: getattr(instance, field) for field in unique_field_order
+                }
+                unique_identifier = tuple(lookup[field] for field in unique_field_order)
                 if unique_identifier not in json_unique_values:
                     instance.is_active = False
                     instance.save()
@@ -208,10 +230,14 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
 
         if changes["created"] or changes["updated"] or changes["deactivated"]:
             logger.info(
-                f"Data changes for ReadOnlyInterface '{parent_class.__name__}': "
-                f"Created: {len(changes['created'])}, "
-                f"Updated: {len(changes['updated'])}, "
-                f"Deactivated: {len(changes['deactivated'])}"
+                "readonly data synchronized",
+                context={
+                    "manager": parent_class.__name__,
+                    "model": model.__name__,
+                    "created": len(changes["created"]),
+                    "updated": len(changes["updated"]),
+                    "deactivated": len(changes["deactivated"]),
+                },
             )
 
     @staticmethod

general_manager/logging.py

@@ -0,0 +1,133 @@
+"""
+Shared logging utilities for the GeneralManager package.
+
+The helpers defined here keep logger names consistent (``general_manager.*``),
+expose lightweight context support, and stay fully compatible with Django's
+``LOGGING`` settings.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping, MutableMapping
+from typing import Any, cast
+
+BASE_LOGGER_NAME = "general_manager"
+COMPONENT_EXTRA_FIELD = "component"
+CONTEXT_EXTRA_FIELD = "context"
+
+
+class InvalidContextError(TypeError):
+    def __init__(self) -> None:
+        super().__init__("context must be a mapping when provided.")
+
+
+class InvalidExtraError(TypeError):
+    def __init__(self) -> None:
+        super().__init__("extra must be a mutable mapping.")
+
+
+class BlankComponentError(ValueError):
+    def __init__(self) -> None:
+        super().__init__("component cannot be blank or only dots.")
+
+
+__all__ = [
+    "BASE_LOGGER_NAME",
+    "COMPONENT_EXTRA_FIELD",
+    "CONTEXT_EXTRA_FIELD",
+    "GeneralManagerLoggerAdapter",
+    "build_logger_name",
+    "get_logger",
+]
+
+
+class GeneralManagerLoggerAdapter(logging.LoggerAdapter[Any]):
+    """
+    Attach structured metadata (component + context) to log records.
+
+    The adapter keeps ``extra`` mutable, merges ``context`` mappings, and can be
+    used anywhere ``logging.Logger`` is expected.
+    """
+
+    def log(self, level: int, msg: Any, *args: Any, **kwargs: Any) -> None:  # type: ignore[override]
+        context_mapping = self._pop_context(kwargs)
+        if context_mapping is not None:
+            kwargs["context"] = context_mapping
+        super().log(level, msg, *args, **kwargs)
+
+    @staticmethod
+    def _pop_context(
+        kwargs: MutableMapping[str, Any],
+    ) -> Mapping[str, Any] | None:
+        context = kwargs.pop("context", None)
+        if context is None:
+            return None
+        if not isinstance(context, Mapping):
+            raise InvalidContextError()
+        return context
+
+    def process(
+        self, msg: Any, kwargs: MutableMapping[str, Any]
+    ) -> tuple[Any, MutableMapping[str, Any]]:
+        context = self._pop_context(kwargs)
+
+        extra_obj = kwargs.setdefault("extra", {})
+        if not isinstance(extra_obj, MutableMapping):
+            raise InvalidExtraError()
+        extra = cast(MutableMapping[str, Any], extra_obj)
+
+        extra_metadata = cast(Mapping[str, Any], self.extra or {})
+        component = extra_metadata.get(COMPONENT_EXTRA_FIELD)
+        if component is not None:
+            extra.setdefault(COMPONENT_EXTRA_FIELD, component)
+
+        if context is not None:
+            current_context = cast(Mapping[str, Any], context)
+            existing_context = extra.get(CONTEXT_EXTRA_FIELD)
+            if existing_context is None:
+                merged_context: dict[str, Any] = dict(current_context)
+            elif isinstance(existing_context, Mapping):
+                merged_context = {**dict(existing_context), **current_context}
+            else:
+                raise InvalidContextError()
+
+            extra[CONTEXT_EXTRA_FIELD] = merged_context
+
+        return msg, kwargs
+
+
+def _normalize_component_name(component: str | None) -> str | None:
+    if component is None:
+        return None
+
+    normalized = component.strip().strip(".")
+    if not normalized:
+        raise BlankComponentError()
+
+    return normalized.replace(" ", "_")
+
+
+def build_logger_name(component: str | None = None) -> str:
+    """
+    Build a fully-qualified logger name within the ``general_manager`` namespace.
+    """
+
+    normalized_component = _normalize_component_name(component)
+    if not normalized_component:
+        return BASE_LOGGER_NAME
+
+    return ".".join([BASE_LOGGER_NAME, normalized_component])
+
+
+def get_logger(component: str | None = None) -> GeneralManagerLoggerAdapter:
+    """
+    Return a ``GeneralManagerLoggerAdapter`` scoped to the requested component.
+    """
+
+    normalized_component = _normalize_component_name(component)
+    logger_name = build_logger_name(normalized_component)
+    adapter_extra: dict[str, Any] = {}
+    if normalized_component:
+        adapter_extra[COMPONENT_EXTRA_FIELD] = normalized_component
+    return GeneralManagerLoggerAdapter(logging.getLogger(logger_name), adapter_extra)

general_manager/manager/general_manager.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Iterator, Self, Type
-from general_manager.manager.meta import GeneralManagerMeta
 
 from general_manager.api.property import GraphQLProperty
+from general_manager.bucket.base_bucket import Bucket
 from general_manager.cache.cache_tracker import DependencyTracker
 from general_manager.cache.signals import data_change
-from general_manager.bucket.base_bucket import Bucket
+from general_manager.logging import get_logger
+from general_manager.manager.meta import GeneralManagerMeta
 
 
 class UnsupportedUnionOperandError(TypeError):
@@ -26,6 +27,9 @@ if TYPE_CHECKING:
     from general_manager.interface.base_interface import InterfaceBase
 
 
+logger = get_logger("manager.general")
+
+
 class GeneralManager(metaclass=GeneralManagerMeta):
     Permission: Type[BasePermission]
     _attributes: dict[str, Any]
@@ -45,6 +49,13 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         DependencyTracker.track(
             self.__class__.__name__, "identification", f"{self.__id}"
         )
+        logger.debug(
+            "instantiated manager",
+            context={
+                "manager": self.__class__.__name__,
+                "identification": self.__id,
+            },
+        )
 
     def __str__(self) -> str:
         """Return a user-friendly representation showing the identification."""
@@ -145,7 +156,17 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         identification = cls.Interface.create(
             creator_id=creator_id, history_comment=history_comment, **kwargs
         )
-        return cls(identification)
+        logger.info(
+            "manager created",
+            context={
+                "manager": cls.__name__,
+                "creator_id": creator_id,
+                "ignore_permission": ignore_permission,
+                "fields": sorted(kwargs.keys()),
+                "identification": identification,
+            },
+        )
+        return cls(**identification)
 
     @data_change
     def update(
@@ -177,6 +198,16 @@ class GeneralManager(metaclass=GeneralManagerMeta):
             history_comment=history_comment,
             **kwargs,
         )
+        logger.info(
+            "manager updated",
+            context={
+                "manager": self.__class__.__name__,
+                "creator_id": creator_id,
+                "ignore_permission": ignore_permission,
+                "fields": sorted(kwargs.keys()),
+                "identification": self.identification,
+            },
+        )
         return self.__class__(**self.identification)
 
     @data_change
@@ -205,6 +236,15 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         self._interface.deactivate(
             creator_id=creator_id, history_comment=history_comment
         )
+        logger.info(
+            "manager deactivated",
+            context={
+                "manager": self.__class__.__name__,
+                "creator_id": creator_id,
+                "ignore_permission": ignore_permission,
+                "identification": self.identification,
+            },
+        )
         return self.__class__(**self.identification)
 
     @classmethod
@@ -218,8 +258,14 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         Returns:
             Bucket[Self]: Bucket of matching manager instances.
         """
-        DependencyTracker.track(
-            cls.__name__, "filter", f"{cls.__parse_identification(kwargs)}"
+        identifier_map = cls.__parse_identification(kwargs) or kwargs
+        DependencyTracker.track(cls.__name__, "filter", repr(identifier_map))
+        logger.debug(
+            "manager filter",
+            context={
+                "manager": cls.__name__,
+                "filters": identifier_map,
+            },
         )
         return cls.Interface.filter(**kwargs)
 
@@ -234,14 +280,26 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         Returns:
             Bucket[Self]: Bucket of manager instances that do not satisfy the lookups.
         """
-        DependencyTracker.track(
-            cls.__name__, "exclude", f"{cls.__parse_identification(kwargs)}"
+        identifier_map = cls.__parse_identification(kwargs) or kwargs
+        DependencyTracker.track(cls.__name__, "exclude", repr(identifier_map))
+        logger.debug(
+            "manager exclude",
+            context={
+                "manager": cls.__name__,
+                "filters": identifier_map,
+            },
         )
         return cls.Interface.exclude(**kwargs)
 
     @classmethod
     def all(cls) -> Bucket[Self]:
         """Return a bucket containing every managed object of this class."""
+        logger.debug(
+            "manager all",
+            context={
+                "manager": cls.__name__,
+            },
+        )
         return cls.Interface.filter()
 
     @staticmethod

general_manager/manager/meta.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 from django.conf import settings
-from typing import Any, Type, TYPE_CHECKING, ClassVar, TypeVar, Iterable, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Iterable, Type, TypeVar, cast
+
 from general_manager.interface.base_interface import InterfaceBase
+from general_manager.logging import get_logger
 
 if TYPE_CHECKING:
     from general_manager.manager.general_manager import GeneralManager
@@ -12,6 +14,8 @@ if TYPE_CHECKING:
 
 GeneralManagerType = TypeVar("GeneralManagerType", bound="GeneralManager")
 
+logger = get_logger("manager.meta")
+
 
 class InvalidInterfaceTypeError(TypeError):
     """Raised when a GeneralManager is configured with an incompatible Interface class."""
@@ -89,6 +93,14 @@ class GeneralManagerMeta(type):
         Returns:
             type: The newly created subclass, possibly modified by Interface hooks.
         """
+        logger.debug(
+            "creating manager class",
+            context={
+                "class_name": name,
+                "module": attrs.get("__module__"),
+                "has_interface": "Interface" in attrs,
+            },
+        )
 
         def create_new_general_manager_class(
             mcs: type["GeneralManagerMeta"],
@@ -109,12 +121,31 @@ class GeneralManagerMeta(type):
             post_creation(new_class, interface_cls, model)
             mcs.pending_attribute_initialization.append(new_class)
             mcs.all_classes.append(new_class)
+            logger.debug(
+                "registered manager class with interface",
+                context={
+                    "class_name": new_class.__name__,
+                    "interface": interface_cls.__name__,
+                },
+            )
 
         else:
             new_class = create_new_general_manager_class(mcs, name, bases, attrs)
+            logger.debug(
+                "registered manager class without interface",
+                context={
+                    "class_name": new_class.__name__,
+                },
+            )
 
         if getattr(settings, "AUTOCREATE_GRAPHQL", False):
             mcs.pending_graphql_interfaces.append(new_class)
+            logger.debug(
+                "queued manager for graphql generation",
+                context={
+                    "class_name": new_class.__name__,
+                },
+            )
 
         return new_class
 
@@ -179,6 +210,13 @@ class GeneralManagerMeta(type):
                         return self._class.Interface.get_field_type(self._attr_name)
                     attribute = instance._attributes.get(self._attr_name, _nonExistent)
                     if attribute is _nonExistent:
+                        logger.warning(
+                            "missing attribute on manager instance",
+                            context={
+                                "attribute": self._attr_name,
+                                "manager": instance.__class__.__name__,
+                            },
+                        )
                         raise MissingAttributeError(
                             self._attr_name, instance.__class__.__name__
                         )
@@ -186,6 +224,14 @@ class GeneralManagerMeta(type):
                         try:
                             attribute = attribute(instance._interface)
                         except Exception as e:
+                            logger.exception(
+                                "attribute evaluation failed",
+                                context={
+                                    "attribute": self._attr_name,
+                                    "manager": instance.__class__.__name__,
+                                    "error": type(e).__name__,
+                                },
+                            )
                             raise AttributeEvaluationError(self._attr_name, e) from e
                     return attribute
 

general_manager/permission/base_permission.py

@@ -1,23 +1,25 @@
 """Base permission contract used by GeneralManager instances."""
 
 from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, Literal, TypeAlias, cast
-from general_manager.permission.permission_checks import permission_functions
 
-from django.contrib.auth.models import AnonymousUser, AbstractBaseUser, AbstractUser
+from django.contrib.auth.models import AbstractBaseUser, AbstractUser, AnonymousUser
+
+from general_manager.logging import get_logger
+from general_manager.permission.permission_checks import permission_functions
 from general_manager.permission.permission_data_manager import PermissionDataManager
 from general_manager.permission.utils import (
-    validate_permission_string,
     PermissionNotFoundError,
+    validate_permission_string,
 )
-import logging
 
 if TYPE_CHECKING:
     from general_manager.manager.general_manager import GeneralManager
     from general_manager.manager.meta import GeneralManagerMeta
 
-logger = logging.getLogger(__name__)
+logger = get_logger("permission.base")
 
 UserLike: TypeAlias = AbstractBaseUser | AnonymousUser
 
@@ -86,11 +88,18 @@ class BasePermission(ABC):
         errors = []
         permission_data = PermissionDataManager(permission_data=data, manager=manager)
         Permission = cls(permission_data, request_user)
+        user_identifier = getattr(request_user, "id", None)
         for key in data.keys():
             is_allowed = Permission.check_permission("create", key)
             if not is_allowed:
-                logger.debug(
-                    f"Permission denied for {key} with value {data[key]} for user {request_user}"
+                logger.info(
+                    "permission denied",
+                    context={
+                        "manager": manager.__name__,
+                        "action": "create",
+                        "attribute": key,
+                        "user_id": user_identifier,
+                    },
                 )
                 errors.append(f"Create permission denied for attribute '{key}'")
         if errors:
@@ -121,11 +130,18 @@ class BasePermission(ABC):
             base_data=old_manager_instance, update_data=data
         )
         Permission = cls(permission_data, request_user)
+        user_identifier = getattr(request_user, "id", None)
         for key in data.keys():
             is_allowed = Permission.check_permission("update", key)
             if not is_allowed:
-                logger.debug(
-                    f"Permission denied for {key} with value {data[key]} for user {request_user}"
+                logger.info(
+                    "permission denied",
+                    context={
+                        "manager": old_manager_instance.__class__.__name__,
+                        "action": "update",
+                        "attribute": key,
+                        "user_id": user_identifier,
+                    },
                 )
                 errors.append(f"Update permission denied for attribute '{key}'")
         if errors:
@@ -154,11 +170,18 @@ class BasePermission(ABC):
         errors = []
         permission_data = PermissionDataManager(manager_instance)
         Permission = cls(permission_data, request_user)
+        user_identifier = getattr(request_user, "id", None)
         for key in manager_instance.__dict__.keys():
             is_allowed = Permission.check_permission("delete", key)
             if not is_allowed:
-                logger.debug(
-                    f"Permission denied for {key} with value {getattr(manager_instance, key)} for user {request_user}"
+                logger.info(
+                    "permission denied",
+                    context={
+                        "manager": manager_instance.__class__.__name__,
+                        "action": "delete",
+                        "attribute": key,
+                        "user_id": user_identifier,
+                    },
                 )
                 errors.append(f"Delete permission denied for attribute '{key}'")
         if errors:
@@ -185,8 +208,8 @@ class BasePermission(ABC):
         if isinstance(user, (AbstractBaseUser, AnonymousUser)):
             return user
         try:
-            return User.objects.get(id=user)
-        except User.DoesNotExist:
+            return User.objects.get(pk=user)
+        except (User.DoesNotExist, ValueError, TypeError):
             return AnonymousUser()
 
     @abstractmethod

general_manager/public_api_registry.py

@@ -18,6 +18,7 @@ GENERAL_MANAGER_EXPORTS: LazyExportMap = {
     "graph_ql_mutation": ("general_manager.api.mutation", "graph_ql_mutation"),
     "GeneralManager": ("general_manager.manager.general_manager", "GeneralManager"),
     "Input": ("general_manager.manager.input", "Input"),
+    "get_logger": ("general_manager.logging", "get_logger"),
     "CalculationInterface": (
         "general_manager.interface.calculation_interface",
         "CalculationInterface",