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

general_manager/_types/general_manager.py

@@ -11,6 +11,7 @@ __all__ = [
     "ManagerBasedPermission",
     "ReadOnlyInterface",
     "Rule",
+    "get_logger",
     "graph_ql_mutation",
     "graph_ql_property",
 ]
@@ -23,5 +24,6 @@ from general_manager.manager.input import Input
 from general_manager.permission.manager_based_permission import ManagerBasedPermission
 from general_manager.interface.read_only_interface import ReadOnlyInterface
 from general_manager.rule.rule import Rule
+from general_manager.logging import get_logger
 from general_manager.api.mutation import graph_ql_mutation
 from general_manager.api.property import graph_ql_property

general_manager/api/graphql.py

@@ -39,11 +39,12 @@ from graphql.language.ast import (
 from asgiref.sync import async_to_sync
 from channels.layers import BaseChannelLayer, get_channel_layer
 
+from general_manager.bucket.base_bucket import Bucket
 from general_manager.cache.cache_tracker import DependencyTracker
 from general_manager.cache.dependency_index import Dependency
 from general_manager.cache.signals import post_data_change
-from general_manager.bucket.base_bucket import Bucket
 from general_manager.interface.base_interface import InterfaceBase
+from general_manager.logging import get_logger
 from general_manager.manager.general_manager import GeneralManager
 from general_manager.measurement.measurement import Measurement
 
@@ -57,6 +58,9 @@ if TYPE_CHECKING:
     from graphene import ResolveInfo as GraphQLResolveInfo
 
 
+logger = get_logger("api.graphql")
+
+
 @dataclass(slots=True)
 class SubscriptionEvent:
     """Payload delivered to GraphQL subscription resolvers."""
@@ -345,18 +349,39 @@ class GraphQL:
             cls._mutations[create_name] = cls.generate_create_mutation_class(
                 generalManagerClass, default_return_values
             )
+            logger.debug(
+                "registered graphql mutation",
+                context={
+                    "manager": generalManagerClass.__name__,
+                    "mutation": create_name,
+                },
+            )
 
         if InterfaceBase.update.__code__ != interface_cls.update.__code__:
             update_name = f"update{generalManagerClass.__name__}"
             cls._mutations[update_name] = cls.generate_update_mutation_class(
                 generalManagerClass, default_return_values
             )
+            logger.debug(
+                "registered graphql mutation",
+                context={
+                    "manager": generalManagerClass.__name__,
+                    "mutation": update_name,
+                },
+            )
 
         if InterfaceBase.deactivate.__code__ != interface_cls.deactivate.__code__:
             delete_name = f"delete{generalManagerClass.__name__}"
             cls._mutations[delete_name] = cls.generate_delete_mutation_class(
                 generalManagerClass, default_return_values
             )
+            logger.debug(
+                "registered graphql mutation",
+                context={
+                    "manager": generalManagerClass.__name__,
+                    "mutation": delete_name,
+                },
+            )
 
     @classmethod
     def create_graphql_interface(
@@ -376,6 +401,11 @@ class GraphQL:
         if not interface_cls:
             return None
 
+        logger.info(
+            "building graphql interface",
+            context={"manager": generalManagerClass.__name__},
+        )
+
         graphene_type_name = f"{generalManagerClass.__name__}Type"
         fields: dict[str, Any] = {}
 
@@ -434,6 +464,16 @@ class GraphQL:
         cls.manager_registry[generalManagerClass.__name__] = generalManagerClass
         cls._add_queries_to_schema(graphene_type, generalManagerClass)
         cls._add_subscription_field(graphene_type, generalManagerClass)
+        exposed_fields = sorted(
+            name for name in fields.keys() if not name.startswith("resolve_")
+        )
+        logger.debug(
+            "registered graphql interface",
+            context={
+                "manager": generalManagerClass.__name__,
+                "fields": exposed_fields,
+            },
+        )
 
     @staticmethod
     def _sort_by_options(
@@ -1811,23 +1851,47 @@ class GraphQL:
         Returns:
             GraphQLError: GraphQL error containing the original message and an `extensions['code']` indicating the error category.
         """
+        message = str(error)
+        error_name = type(error).__name__
         if isinstance(error, PermissionError):
+            logger.info(
+                "graphql permission error",
+                context={
+                    "error": error_name,
+                    "message": message,
+                },
+            )
             return GraphQLError(
-                str(error),
+                message,
                 extensions={
                     "code": "PERMISSION_DENIED",
                 },
             )
         elif isinstance(error, (ValueError, ValidationError, TypeError)):
+            logger.warning(
+                "graphql user error",
+                context={
+                    "error": error_name,
+                    "message": message,
+                },
+            )
             return GraphQLError(
-                str(error),
+                message,
                 extensions={
                     "code": "BAD_USER_INPUT",
                 },
             )
         else:
+            logger.error(
+                "graphql internal error",
+                context={
+                    "error": error_name,
+                    "message": message,
+                },
+                exc_info=error,
+            )
             return GraphQLError(
-                str(error),
+                message,
                 extensions={
                     "code": "INTERNAL_SERVER_ERROR",
                 },
@@ -1860,10 +1924,24 @@ class GraphQL:
             manager_class = instance.__class__
 
         if manager_class.__name__ not in cls.manager_registry:
+            logger.debug(
+                "skipping subscription event for unregistered manager",
+                context={
+                    "manager": manager_class.__name__,
+                    "action": action,
+                },
+            )
             return
 
         channel_layer = cls._get_channel_layer()
         if channel_layer is None:
+            logger.warning(
+                "channel layer unavailable for subscription event",
+                context={
+                    "manager": manager_class.__name__,
+                    "action": action,
+                },
+            )
             return
 
         group_name = cls._group_name(manager_class, instance.identification)
@@ -1874,6 +1952,14 @@ class GraphQL:
                 "action": action,
             },
         )
+        logger.debug(
+            "dispatched subscription event",
+            context={
+                "manager": manager_class.__name__,
+                "action": action,
+                "group": group_name,
+            },
+        )
 
 
 post_data_change.connect(GraphQL._handle_data_change, weak=False)

general_manager/apps.py

@@ -1,22 +1,25 @@
 from __future__ import annotations
-from django.apps import AppConfig
-import graphene  # type: ignore[import]
+
+import importlib.abc
 import os
+import sys
+from importlib import import_module, util
+from typing import TYPE_CHECKING, Any, Callable, Type, cast
+
+import graphene  # type: ignore[import]
+from django.apps import AppConfig
 from django.conf import settings
+from django.core.checks import register
+from django.core.management.base import BaseCommand
 from django.urls import path, re_path
 from graphene_django.views import GraphQLView  # type: ignore[import]
-from importlib import import_module, util
-import importlib.abc
-import sys
+
+from general_manager.api.graphql import GraphQL
+from general_manager.api.property import graph_ql_property
+from general_manager.logging import get_logger
 from general_manager.manager.general_manager import GeneralManager
-from general_manager.manager.meta import GeneralManagerMeta
 from general_manager.manager.input import Input
-from general_manager.api.property import graph_ql_property
-from general_manager.api.graphql import GraphQL
-from typing import TYPE_CHECKING, Any, Callable, Type, cast
-from django.core.checks import register
-import logging
-from django.core.management.base import BaseCommand
+from general_manager.manager.meta import GeneralManagerMeta
 
 
 class MissingRootUrlconfError(RuntimeError):
@@ -45,7 +48,7 @@ class InvalidPermissionClassError(TypeError):
 if TYPE_CHECKING:
     from general_manager.interface.read_only_interface import ReadOnlyInterface
 
-logger = logging.getLogger(__name__)
+logger = get_logger("apps")
 
 
 class GeneralmanagerConfig(AppConfig):
@@ -79,7 +82,10 @@ class GeneralmanagerConfig(AppConfig):
         GeneralmanagerConfig.patch_read_only_interface_sync(read_only_classes)
         from general_manager.interface.read_only_interface import ReadOnlyInterface
 
-        logger.debug("starting to register ReadOnlyInterface schema warnings...")
+        logger.debug(
+            "registering read-only schema checks",
+            context={"count": len(read_only_classes)},
+        )
 
         def _build_schema_check(
             manager_cls: Type[GeneralManager], model: Any
@@ -154,14 +160,27 @@ class GeneralmanagerConfig(AppConfig):
             run_main = os.environ.get("RUN_MAIN") == "true"
             command = argv[1] if len(argv) > 1 else None
             if command != "runserver" or run_main:
-                logger.debug("start syncing ReadOnlyInterface data...")
+                logger.debug(
+                    "syncing read-only interfaces",
+                    context={
+                        "command": command,
+                        "autoreload": not run_main if command == "runserver" else False,
+                        "count": len(general_manager_classes),
+                    },
+                )
                 for general_manager_class in general_manager_classes:
                     read_only_interface = cast(
                         Type[ReadOnlyInterface], general_manager_class.Interface
                     )
                     read_only_interface.sync_data()
 
-                logger.debug("finished syncing ReadOnlyInterface data.")
+                logger.debug(
+                    "finished syncing read-only interfaces",
+                    context={
+                        "command": command,
+                        "count": len(general_manager_classes),
+                    },
+                )
 
             result = original_run_from_argv(self, argv)
             return result
@@ -182,7 +201,13 @@ class GeneralmanagerConfig(AppConfig):
             pending_attribute_initialization (list[type[GeneralManager]]): GeneralManager classes whose Interface attributes need to be initialized and whose attribute properties should be created.
             all_classes (list[type[GeneralManager]]): All registered GeneralManager classes to inspect for input-field connections and to validate permissions.
         """
-        logger.debug("Initializing GeneralManager classes...")
+        logger.debug(
+            "initializing general manager classes",
+            context={
+                "pending_attributes": len(pending_attribute_initialization),
+                "total": len(all_classes),
+            },
+        )
 
         def _build_connection_resolver(
             attribute_key: str, manager_cls: Type[GeneralManager]
@@ -204,7 +229,10 @@ class GeneralmanagerConfig(AppConfig):
             resolver.__annotations__ = {"return": manager_cls}
             return resolver
 
-        logger.debug("starting to create attributes for GeneralManager classes...")
+        logger.debug(
+            "creating manager attributes",
+            context={"pending_attributes": len(pending_attribute_initialization)},
+        )
         for general_manager_class in pending_attribute_initialization:
             attributes = general_manager_class.Interface.get_attributes()
             general_manager_class._attributes = attributes
@@ -212,7 +240,10 @@ class GeneralmanagerConfig(AppConfig):
                 attributes.keys(), general_manager_class
             )
 
-        logger.debug("starting to connect inputs to other general manager classes...")
+        logger.debug(
+            "linking manager inputs",
+            context={"total_classes": len(all_classes)},
+        )
         for general_manager_class in all_classes:
             attributes = getattr(general_manager_class.Interface, "input_fields", {})
             for attribute_name, attribute in attributes.items():
@@ -241,7 +272,10 @@ class GeneralmanagerConfig(AppConfig):
         Parameters:
             pending_graphql_interfaces (list[Type[GeneralManager]]): GeneralManager classes for which GraphQL interfaces, mutations, and optional subscriptions should be created and included in the assembled schema.
         """
-        logger.debug("Starting to create GraphQL interfaces and mutations...")
+        logger.debug(
+            "creating graphql interfaces and mutations",
+            context={"pending": len(GeneralManagerMeta.pending_graphql_interfaces)},
+        )
         for general_manager_class in pending_graphql_interfaces:
             GraphQL.create_graphql_interface(general_manager_class)
             GraphQL.create_graphql_mutation(general_manager_class)
@@ -292,7 +326,13 @@ class GeneralmanagerConfig(AppConfig):
         Raises:
             MissingRootUrlconfError: If ROOT_URLCONF is not defined in Django settings.
         """
-        logging.debug("Adding GraphQL URL to Django settings...")
+        logger.debug(
+            "configuring graphql http endpoint",
+            context={
+                "root_urlconf": getattr(settings, "ROOT_URLCONF", None),
+                "graphql_url": getattr(settings, "GRAPHQL_URL", "graphql"),
+            },
+        )
         root_url_conf_path = getattr(settings, "ROOT_URLCONF", None)
         graph_ql_url = getattr(settings, "GRAPHQL_URL", "graphql")
         if not root_url_conf_path:
@@ -317,15 +357,18 @@ class GeneralmanagerConfig(AppConfig):
         """
         asgi_path = getattr(settings, "ASGI_APPLICATION", None)
         if not asgi_path:
-            logger.debug("ASGI_APPLICATION not configured; skipping websocket setup.")
+            logger.debug(
+                "asgi application missing",
+                context={"graphql_url": graphql_url},
+            )
             return
 
         try:
             module_path, attr_name = asgi_path.rsplit(".", 1)
         except ValueError:
             logger.warning(
-                "ASGI_APPLICATION '%s' is not a valid module path; skipping websocket setup.",
-                asgi_path,
+                "invalid asgi application path",
+                context={"asgi_application": asgi_path},
             )
             return
 
@@ -334,9 +377,12 @@ class GeneralmanagerConfig(AppConfig):
         except RuntimeError as exc:
             if "populate() isn't reentrant" not in str(exc):
                 logger.warning(
-                    "Unable to import ASGI module '%s': %s",
-                    module_path,
-                    exc,
+                    "unable to import asgi module",
+                    context={
+                        "module": module_path,
+                        "error": type(exc).__name__,
+                        "message": str(exc),
+                    },
                     exc_info=True,
                 )
                 return
@@ -344,8 +390,8 @@ class GeneralmanagerConfig(AppConfig):
             spec = util.find_spec(module_path)
             if spec is None or spec.loader is None:
                 logger.warning(
-                    "Could not locate loader for ASGI module '%s'; skipping websocket setup.",
-                    module_path,
+                    "missing loader for asgi module",
+                    context={"module": module_path},
                 )
                 return
 
@@ -416,7 +462,13 @@ class GeneralmanagerConfig(AppConfig):
             return
         except ImportError as exc:  # pragma: no cover - defensive
             logger.warning(
-                "Unable to import ASGI module '%s': %s", module_path, exc, exc_info=True
+                "unable to import asgi module",
+                context={
+                    "module": module_path,
+                    "error": type(exc).__name__,
+                    "message": str(exc),
+                },
+                exc_info=True,
             )
             return
 
@@ -447,8 +499,11 @@ class GeneralmanagerConfig(AppConfig):
             RuntimeError,
         ) as exc:  # pragma: no cover - optional dependency
             logger.debug(
-                "Channels or GraphQL subscription consumer unavailable (%s); skipping websocket setup.",
-                exc,
+                "channels dependencies unavailable",
+                context={
+                    "error": type(exc).__name__,
+                    "message": str(exc),
+                },
             )
             return
 
@@ -459,8 +514,8 @@ class GeneralmanagerConfig(AppConfig):
 
         if not hasattr(websocket_patterns, "append"):
             logger.warning(
-                "websocket_urlpatterns in '%s' does not support appending; skipping websocket setup.",
-                asgi_module.__name__,
+                "websocket_urlpatterns not appendable",
+                context={"module": asgi_module.__name__},
             )
             return
 

general_manager/cache/cache_decorator.py

@@ -1,11 +1,14 @@
 """Helpers for caching GeneralManager computations with dependency tracking."""
 
-from typing import Any, Callable, Optional, Protocol, Set, TypeVar, cast
 from functools import wraps
+from typing import Any, Callable, Optional, Protocol, Set, TypeVar, cast
+
 from django.core.cache import cache as django_cache
+
 from general_manager.cache.cache_tracker import DependencyTracker
-from general_manager.cache.dependency_index import record_dependencies, Dependency
+from general_manager.cache.dependency_index import Dependency, record_dependencies
 from general_manager.cache.model_dependency_collector import ModelDependencyCollector
+from general_manager.logging import get_logger
 from general_manager.utils.make_cache_key import make_cache_key
 
 
@@ -42,6 +45,7 @@ RecordFn = Callable[[str, Set[Dependency]], None]
 FuncT = TypeVar("FuncT", bound=Callable[..., object])
 
 _SENTINEL = object()
+logger = get_logger("cache.decorator")
 
 
 def cached(
@@ -74,6 +78,14 @@ def cached(
                 if cached_deps:
                     for class_name, operation, identifier in cached_deps:
                         DependencyTracker.track(class_name, operation, identifier)
+                logger.debug(
+                    "cache hit",
+                    context={
+                        "function": func.__qualname__,
+                        "key": key,
+                        "dependency_count": len(cached_deps) if cached_deps else 0,
+                    },
+                )
                 return cached_result
 
             with DependencyTracker() as dependencies:
@@ -86,6 +98,15 @@ def cached(
                 if dependencies and timeout is None:
                     record_fn(key, dependencies)
 
+            logger.debug(
+                "cache miss recorded",
+                context={
+                    "function": func.__qualname__,
+                    "key": key,
+                    "dependency_count": len(dependencies),
+                    "timeout": timeout,
+                },
+            )
             return result
 
         # fix for python 3.14:

general_manager/cache/dependency_index.py

@@ -1,16 +1,18 @@
 """Dependency index management for cached GeneralManager query results."""
 
 from __future__ import annotations
-import time
+
 import ast
 import re
-import logging
+import time
 from datetime import date, datetime
+from typing import TYPE_CHECKING, Any, Iterable, Literal, Tuple, Type, cast
 
 from django.core.cache import cache
-from general_manager.cache.signals import post_data_change, pre_data_change
 from django.dispatch import receiver
-from typing import Literal, Any, Iterable, TYPE_CHECKING, Type, Tuple, cast
+
+from general_manager.cache.signals import post_data_change, pre_data_change
+from general_manager.logging import get_logger
 
 if TYPE_CHECKING:
     from general_manager.manager.general_manager import GeneralManager
@@ -31,7 +33,7 @@ type dependency_index = dict[
 type filter_type = Literal["filter", "exclude", "identification"]
 type Dependency = Tuple[general_manager_name, filter_type, str]
 
-logger = logging.getLogger(__name__)
+logger = get_logger("cache.dependency_index")
 
 
 class DependencyLockTimeoutError(TimeoutError):
@@ -616,7 +618,14 @@ def generic_cache_invalidation(
                         )
                         if should_invalidate:
                             logger.info(
-                                f"Invalidate cache key {ck} for filter {lookup} with value {val_key}"
+                                "invalidating cache key",
+                                context={
+                                    "manager": manager_name,
+                                    "key": ck,
+                                    "lookup": lookup,
+                                    "action": action,
+                                    "value": val_key,
+                                },
                             )
                             invalidate_cache_key(ck)
                             remove_cache_key_from_index(ck)
@@ -634,7 +643,14 @@ def generic_cache_invalidation(
                         )
                         if should_invalidate:
                             logger.info(
-                                f"Invalidate cache key {ck} for exclude {lookup} with value {val_key}"
+                                "invalidating cache key",
+                                context={
+                                    "manager": manager_name,
+                                    "key": ck,
+                                    "lookup": lookup,
+                                    "action": action,
+                                    "value": val_key,
+                                },
                             )
                             invalidate_cache_key(ck)
                             remove_cache_key_from_index(ck)

general_manager/interface/base_interface.py

@@ -302,7 +302,7 @@ class InterfaceBase(ABC):
                     raise InvalidInputValueError(name, value, allowed_values)
 
     @classmethod
-    def create(cls, *args: Any, **kwargs: Any) -> Any:
+    def create(cls, *args: Any, **kwargs: Any) -> dict[str, Any]:
         """
         Create a new managed record in the underlying data store using the interface's inputs.
 

general_manager/interface/database_interface.py

@@ -69,7 +69,7 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
     @classmethod
     def create(
         cls, creator_id: int | None, history_comment: str | None = None, **kwargs: Any
-    ) -> int:
+    ) -> dict[str, Any]:
         """
         Create a new model instance using the provided field values.
 
@@ -91,11 +91,11 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
         instance = cls.__set_attr_for_write(model_cls(), kwargs)
         pk = cls._save_with_history(instance, creator_id, history_comment)
         cls.__set_many_to_many_attributes(instance, many_to_many_kwargs)
-        return pk
+        return {"id": pk}
 
     def update(
         self, creator_id: int | None, history_comment: str | None = None, **kwargs: Any
-    ) -> int:
+    ) -> dict[str, Any]:
         """
         Update this instance with the provided field values.
 
@@ -117,11 +117,11 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
         instance = self.__set_attr_for_write(model_cls.objects.get(pk=self.pk), kwargs)
         pk = self._save_with_history(instance, creator_id, history_comment)
         self.__set_many_to_many_attributes(instance, many_to_many_kwargs)
-        return pk
+        return {"id": pk}
 
     def deactivate(
         self, creator_id: int | None, history_comment: str | None = None
-    ) -> int:
+    ) -> dict[str, Any]:
         """
         Mark the current model instance as inactive and record the change.
 
@@ -139,7 +139,7 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
             history_comment = f"{history_comment} (deactivated)"
         else:
             history_comment = "Deactivated"
-        return self._save_with_history(instance, creator_id, history_comment)
+        return {"id": self._save_with_history(instance, creator_id, history_comment)}
 
     @staticmethod
     def __set_many_to_many_attributes(

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
 
-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
 
@@ -208,10 +213,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