GeneralManager 0.82.4__tar.gz → 0.83.0__tar.gz

{generalmanager-0.82.4/src/GeneralManager.egg-info → generalmanager-0.83.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.82.4
+Version: 0.83.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

{generalmanager-0.82.4 → generalmanager-0.83.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.82.4"
+version = "0.83.0"
 description = "Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching."
 readme = "README.md"
 authors = [{ name = "Tim Kleindick", email = "tkleindick@yahoo.de" }]

{generalmanager-0.82.4 → generalmanager-0.83.0/src/GeneralManager.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.82.4
+Version: 0.83.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

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/GeneralManager.egg-info/SOURCES.txt

@@ -229,6 +229,7 @@ src/general_manager/management/commands/search_index.py
 src/general_manager/management/commands/search_reconcile.py
 src/general_manager/management/commands/seed_manager_landscape.py
 src/general_manager/management/commands/shell.py
+src/general_manager/management/commands/sync_read_only.py
 src/general_manager/management/commands/workflow_drain_outbox.py
 src/general_manager/management/commands/workflow_replay_dead_letters.py
 src/general_manager/manager/__init__.py
@@ -274,6 +275,7 @@ src/general_manager/search/backend.py
 src/general_manager/search/backend_registry.py
 src/general_manager/search/checks.py
 src/general_manager/search/config.py
+src/general_manager/search/identity.py
 src/general_manager/search/indexer.py
 src/general_manager/search/invalidation.py
 src/general_manager/search/m2m_invalidation.py

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/general_manager/_types/search.py

@@ -18,10 +18,12 @@ __all__ = [
     "SearchConfigSpec",
     "SearchDocument",
     "SearchHit",
+    "SearchIdentityFilterGroup",
     "SearchIndexer",
     "SearchInvalidationRule",
     "SearchResult",
     "TypesenseBackend",
+    "build_search_filters",
     "configure_search_backend",
     "configure_search_backend_from_settings",
     "get_search_backend",
@@ -44,10 +46,12 @@ from general_manager.search.config import SearchConfigProtocol
 from general_manager.search.config import SearchConfigSpec
 from general_manager.search.backend import SearchDocument
 from general_manager.search.backend import SearchHit
+from general_manager.search.identity import SearchIdentityFilterGroup
 from general_manager.search.indexer import SearchIndexer
 from general_manager.search.config import SearchInvalidationRule
 from general_manager.search.backend import SearchResult
 from general_manager.search.backends.typesense import TypesenseBackend
+from general_manager.search.identity import build_search_filters
 from general_manager.search.backend_registry import configure_search_backend
 from general_manager.search.backend_registry import (
     configure_search_backend_from_settings,

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/general_manager/api/graphql_search.py

@@ -41,6 +41,7 @@ from general_manager.measurement.measurement import Measurement
 from general_manager.utils.type_checks import safe_issubclass
 from general_manager.search.backend_registry import get_search_backend
 from general_manager.search.backend import SearchHit
+from general_manager.search.identity import SearchFilters, build_search_filters
 from general_manager.search.registry import (
     get_search_config,
     get_type_label,
@@ -1257,7 +1258,7 @@ def register_search_query(
                 permission_plan,
                 backend_shape=backend_shape,
             )
-            filter_groups = (
+            filter_groups: SearchFilters = (
                 manager_filters or None
                 if decision == "allow_all"
                 else merge_permission_filters(
@@ -1265,6 +1266,9 @@ def register_search_query(
                     permission_plan.filters,
                 )
             )
+            filter_groups = build_search_filters(
+                manager_class, index_name, filter_groups
+            )
             total_hits_for_manager = 0
             candidate_hits_for_manager = 0
             offset_cursor = 0

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/general_manager/bootstrap.py

@@ -191,7 +191,7 @@ def install_startup_hook_runner() -> None:
     ) -> None:
         run_main = os.environ.get("RUN_MAIN") == "true"
         command = argv[1] if len(argv) > 1 else None
-        should_run_hooks = command != "runserver" or run_main
+        should_run_hooks = command != "runserver" or run_main or "--noreload" in argv
         hooks_registry = registered_startup_hook_entries() if should_run_hooks else {}
         if hooks_registry:
             resolver_groups: list[

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/general_manager/interface/capabilities/read_only/management.py

@@ -3,12 +3,14 @@
 from __future__ import annotations
 
 import json
-from collections.abc import Callable, Sequence
-from contextlib import AbstractContextManager
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import AbstractContextManager, contextmanager
+from contextvars import ContextVar
 from hashlib import sha256
 from typing import TYPE_CHECKING, ClassVar, Protocol, TypeVar, cast
 
 from django.core.checks import Warning
+from django.conf import settings
 from django.db import (
     IntegrityError,
     connection as django_connection,
@@ -44,6 +46,19 @@ from ._types import (
 )
 
 logger = get_logger("interface.read_only")
+_automatic_sync_suppressed: ContextVar[bool] = ContextVar(
+    "read_only_automatic_sync_suppressed", default=False
+)
+
+
+@contextmanager
+def _suppress_automatic_sync() -> Iterator[None]:
+    """Let explicit CLI maintenance own sync while other startup hooks still run."""
+    token = _automatic_sync_suppressed.set(True)
+    try:
+        yield
+    finally:
+        _automatic_sync_suppressed.reset(token)
 
 
 class _ColumnDescription(Protocol):
@@ -1156,9 +1171,9 @@ class ReadOnlyManagementCapability(BaseCapability):
         returned. The registered hook catches `MissingReadOnlyBindingError`
         only to tolerate binding metadata becoming unavailable between
         registration and startup execution; other sync errors propagate.
-        Automatic synchronization is skipped when `READ_ONLY_SYNC_ON_STARTUP`
-        is disabled in GeneralManager settings. Explicit `sync_data()` calls
-        remain available.
+        Automatic synchronization uses `READ_ONLY_SYNC_ON_STARTUP`, falling
+        back to Django `DEBUG` when unset. Explicit `sync_data()` calls remain
+        available regardless of that setting.
 
         Parameters:
             interface_cls: Interface class used to derive the bound manager and model.
@@ -1192,7 +1207,9 @@ class ReadOnlyManagementCapability(BaseCapability):
             binding is not available (raises MissingReadOnlyBindingError), logs a debug
             message and returns without raising.
             """
-            if not get_setting("READ_ONLY_SYNC_ON_STARTUP", True):
+            if _automatic_sync_suppressed.get() or not get_setting(
+                "READ_ONLY_SYNC_ON_STARTUP", settings.DEBUG
+            ):
                 return
             try:
                 self.sync_data(interface_cls)

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/general_manager/management/commands/search_index.py

@@ -9,9 +9,8 @@ from django.core.management.base import BaseCommand
 
 from general_manager.logging import get_logger
 from general_manager.search.backend_registry import get_search_backend
-from general_manager.search.indexer import SearchIndexer
+from general_manager.search.indexer import SearchIndexer, _ensure_index
 from general_manager.search.registry import (
-    collect_index_settings,
     get_index_names,
     iter_searchable_managers,
 )
@@ -99,16 +98,7 @@ class Command(BaseCommand):
             target_indexes = get_index_names()
 
         for index_name in sorted(target_indexes):
-            settings_payload = collect_index_settings(index_name)
-            backend.ensure_index(
-                index_name,
-                {
-                    "searchable_fields": settings_payload.searchable_fields,
-                    "filterable_fields": settings_payload.filterable_fields,
-                    "sortable_fields": settings_payload.sortable_fields,
-                    "field_boosts": settings_payload.field_boosts,
-                },
-            )
+            _ensure_index(backend, index_name)
             logger.info(
                 "search index ensured",
                 context={"index": index_name},

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/general_manager/management/commands/search_reconcile.py

@@ -92,13 +92,18 @@ class Command(BaseCommand):
 
         while True:
             result = reconcile_search_indexes(force=force, max_states=max_states)
-            self.stdout.write(
-                self.style.SUCCESS(
-                    "Reconciled "
-                    f"{result.reconciled} search index states "
-                    f"({result.documents} documents, {result.failed} failures)."
-                )
+            summary = (
+                "Reconciled "
+                f"{result.reconciled} search index states "
+                f"({result.documents} documents, {result.failed} failures)."
             )
+            if result.failed:
+                self.stderr.write(self.style.ERROR(summary))
+                if once:
+                    message = "Search reconciliation failed; inspect logs and SearchIndexState.last_error."
+                    raise CommandError(message)
+            else:
+                self.stdout.write(self.style.SUCCESS(summary))
             if once:
                 return
             force = False

generalmanager-0.83.0/src/general_manager/management/commands/sync_read_only.py

@@ -0,0 +1,169 @@
+"""Explicit deployment maintenance for registered read-only managers."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from collections.abc import Iterable, Sequence
+from typing import cast
+
+from django.core.management.base import BaseCommand, CommandError
+from django.db import connections
+
+from general_manager.interface.capabilities.read_only.management import (
+    ReadOnlyManagementCapability,
+    _ReadOnlyInterface,
+    _SchemaConnection,
+    _suppress_automatic_sync,
+)
+from general_manager.interface.infrastructure.startup_hooks import (
+    order_interfaces_by_dependency,
+)
+from general_manager.manager.meta import GeneralManagerMeta
+
+
+def _manager_path(interface: _ReadOnlyInterface) -> str:
+    """Identify a bound manager without importing arbitrary selector input."""
+    manager = interface._parent_class
+    return f"{manager.__module__}.{manager.__qualname__}"
+
+
+def _capability(interface: _ReadOnlyInterface) -> ReadOnlyManagementCapability:
+    """Use the manager's configured management capability, including overrides."""
+    return cast(
+        ReadOnlyManagementCapability,
+        interface.require_capability(
+            "read_only_management", expected_type=ReadOnlyManagementCapability
+        ),
+    )
+
+
+def _select_interfaces(value: object) -> list[_ReadOnlyInterface]:
+    """Validate selectors and include transitive read-only relation dependencies."""
+    interfaces = list(
+        dict.fromkeys(
+            cast(_ReadOnlyInterface, manager.Interface)
+            for manager in GeneralManagerMeta.all_classes
+            if getattr(manager.Interface, "_interface_type", None) == "readonly"
+        )
+    )
+    if value is None:
+        selected = interfaces
+    else:
+        selectors: tuple[object, ...]
+        if isinstance(value, str):
+            selectors = (value,)
+        elif isinstance(value, Iterable):
+            selectors = tuple(value)
+        else:
+            selectors = ()
+        if not selectors or any(
+            not isinstance(selector, str) or not selector for selector in selectors
+        ):
+            message = "--manager must contain one or more nonempty manager names."
+            raise CommandError(message)
+        selected = []
+        for selector in selectors:
+            matches = [
+                interface
+                for interface in interfaces
+                if selector
+                in (interface._parent_class.__name__, _manager_path(interface))
+            ]
+            if not matches:
+                message = f"Unknown read-only manager: {selector}."
+                raise CommandError(message)
+            if len(matches) > 1:
+                paths = ", ".join(sorted(_manager_path(item) for item in matches))
+                message = (
+                    f"Ambiguous read-only manager {selector}; use one of: {paths}."
+                )
+                raise CommandError(message)
+            if matches[0] not in selected:
+                selected.append(matches[0])
+
+    dependencies: dict[_ReadOnlyInterface, set[_ReadOnlyInterface]] = {}
+    pending = list(selected)
+    while pending:
+        interface = pending.pop(0)
+        if interface in dependencies:
+            continue
+        dependencies[interface] = (
+            ReadOnlyManagementCapability._related_readonly_interfaces(interface)
+        )
+        pending.extend(sorted(dependencies[interface], key=_manager_path))
+
+    interface_list = sorted(dependencies, key=_manager_path)
+    ordered = cast(
+        list[_ReadOnlyInterface],
+        order_interfaces_by_dependency(
+            interface_list,
+            lambda interface: set(dependencies[cast(_ReadOnlyInterface, interface)]),
+        ),
+    )
+    positions = {interface: index for index, interface in enumerate(ordered)}
+    if any(
+        positions[dependency] >= positions[interface]
+        for interface in ordered
+        for dependency in dependencies[interface]
+    ):
+        message = "Read-only dependency cycle; cannot determine a safe sync order."
+        raise CommandError(message)
+    return ordered
+
+
+class Command(BaseCommand):
+    help = "Synchronize read-only managers and their dependencies after migrations."
+
+    def add_arguments(self, parser: ArgumentParser) -> None:
+        """Accept repeatable unique class names or module-qualified manager paths."""
+        parser.add_argument(
+            "--manager",
+            action="append",
+            dest="managers",
+            help="Read-only manager name or module-qualified class path. Repeatable; defaults to all.",
+        )
+
+    def run_from_argv(self, argv: Sequence[str]) -> None:
+        """Avoid duplicate automatic read-only sync before this explicit CLI step."""
+        with _suppress_automatic_sync():
+            super().run_from_argv(argv)
+
+    def handle(self, *_args: object, **options: object) -> None:
+        """Preflight all schemas, then sync in dependency order or fail loudly.
+
+        No global transaction is added: completed managers may remain synced if
+        a later manager fails. Re-running the command converges the payloads.
+        """
+        interfaces = _select_interfaces(options.get("managers"))
+        # The public sync API logs schema warnings and returns without writing.
+        # Deployment maintenance must instead fail before claiming success.
+        for interface in interfaces:
+            try:
+                capability = _capability(interface)
+                warnings = capability.ensure_schema_is_up_to_date(
+                    interface,
+                    interface._parent_class,
+                    interface._model,
+                    connection=cast(
+                        _SchemaConnection,
+                        connections[capability._database_alias(interface)],
+                    ),
+                )
+            except Exception as exc:
+                message = f"Read-only schema check failed for {_manager_path(interface)}: {exc}"
+                raise CommandError(message) from exc
+            if warnings:
+                detail = "; ".join(str(warning) for warning in warnings)
+                message = f"Read-only schema check failed for {_manager_path(interface)}: {detail}"
+                raise CommandError(message)
+
+        for interface in interfaces:
+            try:
+                _capability(interface).sync_data(interface, schema_validated=True)
+            except Exception as exc:
+                message = f"Read-only sync failed for {_manager_path(interface)}: {exc}"
+                raise CommandError(message) from exc
+            self.stdout.write(f"Synchronized {_manager_path(interface)}.")
+        self.stdout.write(
+            self.style.SUCCESS(f"Synchronized {len(interfaces)} read-only managers.")
+        )

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/general_manager/public_api_registry.py

@@ -793,6 +793,11 @@ RULE_EXPORTS: LazyExportMap = {
 }
 
 SEARCH_EXPORTS: LazyExportMap = {
+    "SearchIdentityFilterGroup": (
+        "general_manager.search.identity",
+        "SearchIdentityFilterGroup",
+    ),
+    "build_search_filters": ("general_manager.search.identity", "build_search_filters"),
     "FieldConfig": ("general_manager.search.config", "FieldConfig"),
     "IndexConfig": ("general_manager.search.config", "IndexConfig"),
     "SearchConfigProtocol": ("general_manager.search.config", "SearchConfigProtocol"),

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/general_manager/search/backend.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
+import builtins
 from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Protocol, runtime_checkable
 
 
@@ -20,7 +21,10 @@ class SearchDocument:
     protocol does not require adapters to reject mismatches between
     `document.index` and an `index_name` argument. `data` contains
     searchable/stored fields. `field_boosts` and `index_boost` are hints for
-    adapters that support weighted matching. The payload mappings, including
+    adapters that support weighted matching. `identity_fields` maps explicit
+    identity names to native scalar types (`int`, `str`, or `UUID`), including
+    nullable/collection element types. It never coerces document values.
+    The payload mappings, including
     `identification`, are not copied by the model; callers should treat them as
     immutable after handing them to a backend. Dataclass field annotations are
     the validation boundary; this model does not coerce or validate runtime
@@ -36,6 +40,7 @@ class SearchDocument:
     data: Mapping[str, object]
     field_boosts: Mapping[str, float]
     index_boost: float | None = None
+    identity_fields: Mapping[str, builtins.type] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)

{generalmanager-0.82.4 → generalmanager-0.83.0}/src/general_manager/search/backends/dev.py

@@ -10,6 +10,11 @@ from threading import RLock
 from general_manager.search.backend import SearchDocument, SearchHit, SearchResult
 from general_manager.bucket._ordering import normalize_ordering, sort_items
 from general_manager.utils.filter_parser import apply_lookup
+from general_manager.search.identity import (
+    SearchIdentityFilterGroup,
+    identity_lookup,
+    canonical_identity,
+)
 
 
 @dataclass
@@ -176,6 +181,10 @@ class DevSearchBackend:
                 case-sensitive, missing fields behave like `None`, incompatible
                 mixed-type comparisons and invalid lookup/value combinations
                 return `False`, and `None` compares only through `exact`.
+                Explicit `SearchIdentityFilterGroup` equality/membership uses
+                native casts and owner scope without changing these operator
+                rules. Matching document metadata and a present field are
+                required. Plain mappings retain raw comparisons.
             filter_expression (str | None): Unsupported in this backend; passing a value raises NotImplementedError.
             sort (Sequence[str] | None): Signed document data field names.
                 Prefix a field with ``-`` for descending order. If omitted,
@@ -392,12 +401,38 @@ class DevSearchBackend:
             if not all(isinstance(group, Mapping) for group in filters):
                 return False
             return any(self._passes_filters(document, group) for group in filters)
+        if isinstance(filters, SearchIdentityFilterGroup):
+            if filters.type_label is not None and document.type != filters.type_label:
+                return False
         for key, value in filters.items():
-            if "__" in key:
+            identity = None
+            if isinstance(filters, SearchIdentityFilterGroup):
+                identity = identity_lookup(key, filters.identity_fields)
+            if identity is not None:
+                field_name, lookup, native_type = identity
+                if (
+                    field_name not in document.data
+                    or document.identity_fields.get(field_name) is not native_type
+                ):
+                    return False
+            elif "__" in key:
                 field_name, lookup = key.split("__", 1)
             else:
                 field_name, lookup = key, "exact"
             doc_value = document.data.get(field_name)
+            if identity is not None and (
+                lookup != "in" or isinstance(value, (list, tuple, set))
+            ):
+                doc_value = (
+                    [canonical_identity(native_type, item) for item in doc_value]
+                    if isinstance(doc_value, (list, tuple, set))
+                    else canonical_identity(native_type, doc_value)
+                )
+                value = (
+                    [canonical_identity(native_type, item) for item in value]
+                    if isinstance(value, (list, tuple, set))
+                    else canonical_identity(native_type, value)
+                )
             if lookup == "exact" and isinstance(value, (list, tuple, set)):
                 if isinstance(doc_value, (list, tuple, set)):
                     if not set(doc_value).intersection(value):