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

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",

general_manager/rule/rule.py

@@ -19,10 +19,12 @@ from general_manager.rule.handler import (
     SumHandler,
 )
 from general_manager.manager.general_manager import GeneralManager
+from general_manager.logging import get_logger
 
 GeneralManagerType = TypeVar("GeneralManagerType", bound=GeneralManager)
 
 NOTEXISTENT = object()
+logger = get_logger("rule.engine")
 
 
 class NonexistentAttributeError(AttributeError):
@@ -131,6 +133,13 @@ class Rule(Generic[GeneralManagerType]):
             handler_cls: type[BaseRuleHandler] = import_string(path)
             inst = handler_cls()
             self._handlers[inst.function_name] = inst
+        logger.debug(
+            "initialised rule",
+            context={
+                "rule": self._func.__qualname__,
+                "variables": self._variables,
+            },
+        )
 
     @property
     def func(self) -> Callable[[GeneralManagerType], bool]:
@@ -173,12 +182,47 @@ class Rule(Generic[GeneralManagerType]):
         if self._primary_param is not None:
             self._last_args[self._primary_param] = x
 
+        logger.debug(
+            "evaluating rule",
+            context={
+                "rule": self._func.__qualname__,
+                "manager": type(x).__name__,
+            },
+        )
+
         vals = self._extract_variable_values(x)
         if self._ignore_if_none and any(v is None for v in vals.values()):
             self._last_result = None
+            logger.debug(
+                "skipped rule evaluation due to missing values",
+                context={
+                    "rule": self._func.__qualname__,
+                    "manager": type(x).__name__,
+                    "null_variables": [
+                        name for name, value in vals.items() if value is None
+                    ],
+                },
+            )
             return None
 
         self._last_result = self._func(x)
+        if self._last_result:
+            logger.debug(
+                "rule evaluation passed",
+                context={
+                    "rule": self._func.__qualname__,
+                    "manager": type(x).__name__,
+                },
+            )
+        else:
+            logger.info(
+                "rule evaluation failed",
+                context={
+                    "rule": self._func.__qualname__,
+                    "manager": type(x).__name__,
+                    "variables": self._variables,
+                },
+            )
         return self._last_result
 
     def validate_custom_error_message(self) -> None:
@@ -214,6 +258,14 @@ class Rule(Generic[GeneralManagerType]):
         # Validate and substitute template placeholders
         self.validate_custom_error_message()
         vals = self._extract_variable_values(self._last_input)
+        manager_class = type(self._last_input).__name__
+        logger.debug(
+            "generating rule error messages",
+            context={
+                "rule": self._func.__qualname__,
+                "manager": manager_class,
+            },
+        )
 
         if self._custom_error_message:
             formatted = re.sub(
@@ -221,9 +273,34 @@ class Rule(Generic[GeneralManagerType]):
                 lambda m: str(vals.get(m.group(1), m.group(0))),
                 self._custom_error_message,
             )
+            logger.info(
+                "rule produced custom error message",
+                context={
+                    "rule": self._func.__qualname__,
+                    "manager": manager_class,
+                    "variables": self._variables,
+                },
+            )
             return {v: formatted for v in self._variables}
 
         errors = self._generate_error_messages(vals)
+        if errors:
+            logger.info(
+                "rule produced error messages",
+                context={
+                    "rule": self._func.__qualname__,
+                    "manager": manager_class,
+                    "variables": list(errors.keys()),
+                },
+            )
+        else:
+            logger.debug(
+                "rule generated no error messages",
+                context={
+                    "rule": self._func.__qualname__,
+                    "manager": manager_class,
+                },
+            )
         return errors or None
 
     def _extract_variables(self) -> List[str]:
@@ -355,6 +432,14 @@ class Rule(Generic[GeneralManagerType]):
                         fn = self._get_node_name(left.func)
                         handler = self._handlers.get(fn)
                         if handler:
+                            logger.debug(
+                                "rule handler invoked",
+                                context={
+                                    "rule": self._func.__qualname__,
+                                    "handler": handler.__class__.__name__,
+                                    "function": fn,
+                                },
+                            )
                             errors.update(
                                 handler.handle(cmp, left, right, op, var_values, self)
                             )

general_manager/utils/public_api.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 from importlib import import_module
 from typing import Any, Iterable, Mapping, MutableMapping, overload
 
+from general_manager.logging import get_logger
+
 
 class MissingExportError(AttributeError):
     """Raised when a requested export is not defined in the public API."""
@@ -24,6 +26,7 @@ class MissingExportError(AttributeError):
 
 ModuleTarget = tuple[str, str]
 ModuleMap = Mapping[str, str | ModuleTarget]
+logger = get_logger("utils.public_api")
 
 
 @overload
@@ -63,11 +66,27 @@ def resolve_export(
         MissingExportError: If `name` is not present in `module_all`.
     """
     if name not in module_all:
+        logger.warning(
+            "missing public api export",
+            context={
+                "module": module_globals["__name__"],
+                "export": name,
+            },
+        )
         raise MissingExportError(module_globals["__name__"], name)
     module_path, attr_name = _normalize_target(name, module_map[name])
     module = import_module(module_path)
     value = getattr(module, attr_name)
     module_globals[name] = value
+    logger.debug(
+        "resolved public api export",
+        context={
+            "module": module_globals["__name__"],
+            "export": name,
+            "target_module": module_path,
+            "target_attribute": attr_name,
+        },
+    )
     return value
 
 

{generalmanager-0.19.2.dist-info → generalmanager-0.20.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.19.2
+Version: 0.20.0
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: MIT License