GeneralManager 0.77.0__tar.gz → 0.78.0__tar.gz

{generalmanager-0.77.0/src/GeneralManager.egg-info → generalmanager-0.78.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.77.0
+Version: 0.78.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
@@ -61,6 +61,8 @@ Requires-Dist: graphene-django>=3.2.3
 Requires-Dist: graphql-core>=3.2.6
 Requires-Dist: graphql-relay>=3.2.0
 Requires-Dist: numpy>=2.2.5
+Requires-Dist: openpyxl<3.2.0,>=3.1.5
+Requires-Dist: filelock<4,>=3.24.3
 Requires-Dist: Pint>=0.24.4
 Requires-Dist: platformdirs>=4.3.7
 Requires-Dist: promise>=2.3

{generalmanager-0.77.0 → generalmanager-0.78.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.77.0"
+version = "0.78.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" }]
@@ -49,6 +49,8 @@ dependencies = [
     "graphql-core>=3.2.6",
     "graphql-relay>=3.2.0",
     "numpy>=2.2.5",
+    "openpyxl>=3.1.5,<3.2.0",  # Excel workbook IO
+    "filelock>=3.24.3,<4",  # portable process-safe Excel workbook locks
     "Pint>=0.24.4",
     "platformdirs>=4.3.7",
     "promise>=2.3",

{generalmanager-0.77.0 → generalmanager-0.78.0/src/GeneralManager.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.77.0
+Version: 0.78.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
@@ -61,6 +61,8 @@ Requires-Dist: graphene-django>=3.2.3
 Requires-Dist: graphql-core>=3.2.6
 Requires-Dist: graphql-relay>=3.2.0
 Requires-Dist: numpy>=2.2.5
+Requires-Dist: openpyxl<3.2.0,>=3.1.5
+Requires-Dist: filelock<4,>=3.24.3
 Requires-Dist: Pint>=0.24.4
 Requires-Dist: platformdirs>=4.3.7
 Requires-Dist: promise>=2.3

{generalmanager-0.77.0 → generalmanager-0.78.0}/src/GeneralManager.egg-info/SOURCES.txt

@@ -57,6 +57,7 @@ src/general_manager/bucket/__init__.py
 src/general_manager/bucket/base_bucket.py
 src/general_manager/bucket/calculation_bucket.py
 src/general_manager/bucket/database_bucket.py
+src/general_manager/bucket/excel_bucket.py
 src/general_manager/bucket/group_bucket.py
 src/general_manager/bucket/indexing.py
 src/general_manager/bucket/projection.py
@@ -142,11 +143,15 @@ src/general_manager/factory/factories.py
 src/general_manager/factory/factory_methods.py
 src/general_manager/interface/__init__.py
 src/general_manager/interface/base_interface.py
+src/general_manager/interface/excel.py
+src/general_manager/interface/excel_store.py
+src/general_manager/interface/excel_workbook.py
 src/general_manager/interface/orm_interface.py
 src/general_manager/interface/requests.py
 src/general_manager/interface/bundles/__init__.py
 src/general_manager/interface/bundles/calculation.py
 src/general_manager/interface/bundles/database.py
+src/general_manager/interface/bundles/excel.py
 src/general_manager/interface/bundles/remote_manager.py
 src/general_manager/interface/bundles/request.py
 src/general_manager/interface/capabilities/__init__.py
@@ -163,6 +168,7 @@ src/general_manager/interface/capabilities/calculation/input_resolution.py
 src/general_manager/interface/capabilities/calculation/lifecycle.py
 src/general_manager/interface/capabilities/core/observability.py
 src/general_manager/interface/capabilities/core/utils.py
+src/general_manager/interface/capabilities/excel/__init__.py
 src/general_manager/interface/capabilities/existing_model/__init__.py
 src/general_manager/interface/capabilities/existing_model/_compat.py
 src/general_manager/interface/capabilities/existing_model/resolution.py
@@ -188,6 +194,7 @@ src/general_manager/interface/infrastructure/system_checks.py
 src/general_manager/interface/interfaces/__init__.py
 src/general_manager/interface/interfaces/calculation.py
 src/general_manager/interface/interfaces/database.py
+src/general_manager/interface/interfaces/excel.py
 src/general_manager/interface/interfaces/existing_model.py
 src/general_manager/interface/interfaces/read_only.py
 src/general_manager/interface/interfaces/remote_manager.py

{generalmanager-0.77.0 → generalmanager-0.78.0}/src/GeneralManager.egg-info/requires.txt

@@ -15,6 +15,8 @@ graphene-django>=3.2.3
 graphql-core>=3.2.6
 graphql-relay>=3.2.0
 numpy>=2.2.5
+openpyxl<3.2.0,>=3.1.5
+filelock<4,>=3.24.3
 Pint>=0.24.4
 platformdirs>=4.3.7
 promise>=2.3

{generalmanager-0.77.0 → generalmanager-0.78.0}/src/general_manager/_types/general_manager.py

@@ -6,6 +6,11 @@ __all__ = [
     "AdditiveManagerPermission",
     "CalculationInterface",
     "DatabaseInterface",
+    "ExcelCharField",
+    "ExcelDecimalField",
+    "ExcelField",
+    "ExcelIntegerField",
+    "ExcelInterface",
     "ExistingModelInterface",
     "FieldConfig",
     "GeneralManager",
@@ -42,6 +47,11 @@ from general_manager.permission.manager_based_permission import (
 )
 from general_manager.interface.interfaces.calculation import CalculationInterface
 from general_manager.interface.interfaces.database import DatabaseInterface
+from general_manager.interface.excel import ExcelCharField
+from general_manager.interface.excel import ExcelDecimalField
+from general_manager.interface.excel import ExcelField
+from general_manager.interface.excel import ExcelIntegerField
+from general_manager.interface.interfaces.excel import ExcelInterface
 from general_manager.interface.interfaces.existing_model import ExistingModelInterface
 from general_manager.search.config import FieldConfig
 from general_manager.manager.general_manager import GeneralManager

{generalmanager-0.77.0 → generalmanager-0.78.0}/src/general_manager/_types/interface.py

@@ -7,6 +7,11 @@ __all__ = [
     "BearerTokenAuthProvider",
     "CalculationInterface",
     "DatabaseInterface",
+    "ExcelCharField",
+    "ExcelDecimalField",
+    "ExcelField",
+    "ExcelIntegerField",
+    "ExcelInterface",
     "ExistingModelInterface",
     "FieldMappingSerializer",
     "HeaderApiKeyAuthProvider",
@@ -49,6 +54,11 @@ from general_manager.interface.requests import BasicAuthProvider
 from general_manager.interface.requests import BearerTokenAuthProvider
 from general_manager.interface.interfaces.calculation import CalculationInterface
 from general_manager.interface.interfaces.database import DatabaseInterface
+from general_manager.interface.excel import ExcelCharField
+from general_manager.interface.excel import ExcelDecimalField
+from general_manager.interface.excel import ExcelField
+from general_manager.interface.excel import ExcelIntegerField
+from general_manager.interface.interfaces.excel import ExcelInterface
 from general_manager.interface.interfaces.existing_model import ExistingModelInterface
 from general_manager.interface.requests import FieldMappingSerializer
 from general_manager.interface.requests import HeaderApiKeyAuthProvider

generalmanager-0.78.0/src/general_manager/bucket/excel_bucket.py

@@ -0,0 +1,339 @@
+"""Bucket implementation for Excel-backed interfaces."""
+
+from __future__ import annotations
+
+from collections.abc import Generator, Iterable, Mapping
+from typing import Any, Protocol, cast
+
+from general_manager.bucket.base_bucket import Bucket, GeneralManagerType
+from general_manager.cache.cache_tracker import DependencyTracker
+from general_manager.cache.dependency_index import serialize_dependency_identifier
+from general_manager.cache.dependency_matching import lookup_spec_from_key
+from general_manager.interface.excel import ExcelMeta
+from general_manager.interface.excel_store import DEFAULT_EXCEL_STORE
+from general_manager.utils.filter_parser import create_filter_function
+
+SUPPORTED_EXCEL_LOOKUPS = frozenset(
+    {
+        "exact",
+        "lt",
+        "lte",
+        "gt",
+        "gte",
+        "contains",
+        "startswith",
+        "endswith",
+        "in",
+    }
+)
+
+
+class ExcelSingleItemRequiredError(ValueError):
+    def __init__(self) -> None:
+        super().__init__("get() requires exactly one Excel row.")
+
+
+class ExcelBucketLookupError(ValueError):
+    def __init__(self, manager_class: type, lookup: str) -> None:
+        super().__init__(
+            f"Unknown Excel field lookup {lookup!r} for {manager_class.__name__}."
+        )
+
+
+class ExcelBucketUnionError(TypeError):
+    def __init__(
+        self,
+        manager_class: type,
+        other: object,
+        *,
+        other_manager_class: type | None = None,
+    ) -> None:
+        if other_manager_class is not None:
+            message = (
+                f"Cannot union ExcelBucket for {manager_class.__name__} with "
+                f"ExcelBucket for {other_manager_class.__name__}."
+            )
+        else:
+            message = (
+                f"Cannot union ExcelBucket for {manager_class.__name__} with "
+                f"{type(other).__name__}; expected ExcelBucket for "
+                f"{manager_class.__name__} or {manager_class.__name__} instance."
+            )
+        super().__init__(message)
+
+
+class _ExcelRowView:
+    """Attribute view over a parsed Excel row for filter evaluation."""
+
+    def __init__(self, values: Mapping[str, Any]) -> None:
+        self._values = values
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self._values[name]
+        except KeyError as error:
+            raise AttributeError(name) from error
+
+
+class _ExcelInterfaceType(Protocol):
+    excel_meta: ExcelMeta
+    excel_fields: dict[str, Any]
+
+    @classmethod
+    def sync_from_excel(cls, *, force: bool = False) -> object: ...
+
+
+class ExcelBucket(Bucket[GeneralManagerType]):
+    def __init__(
+        self,
+        manager_class: type[GeneralManagerType],
+        interface_cls: _ExcelInterfaceType,
+        *,
+        filters: Mapping[str, Any] | Iterable[tuple[str, Any]] | None = None,
+        excludes: Mapping[str, Any] | Iterable[tuple[str, Any]] | None = None,
+        keys: tuple[Any, ...] | None = None,
+    ) -> None:
+        super().__init__(manager_class)
+        self._interface_cls = interface_cls
+        self._filters = self._normalize_reserved_constraints(filters)
+        self._excludes = self._normalize_reserved_constraints(excludes)
+        self.filters = self._dependency_payload(self._filters)
+        self.excludes = self._dependency_payload(self._excludes)
+        self._keys = keys
+
+    @staticmethod
+    def _normalize_constraints(
+        constraints: Mapping[str, Any] | Iterable[tuple[str, Any]] | None,
+    ) -> tuple[tuple[str, Any], ...]:
+        if constraints is None:
+            return ()
+        if isinstance(constraints, Mapping):
+            return tuple(constraints.items())
+        return tuple(constraints)
+
+    @staticmethod
+    def _dependency_payload(
+        constraints: tuple[tuple[str, Any], ...],
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        for lookup, expected in constraints:
+            dependency_lookup = (
+                lookup.removesuffix("__exact") if lookup.endswith("__exact") else lookup
+            )
+            spec = lookup_spec_from_key(dependency_lookup)
+            normalized_lookup = "__".join(spec.attr_path)
+            if spec.operator != "eq":
+                normalized_lookup = f"{normalized_lookup}__{spec.operator}"
+            payload[normalized_lookup] = expected
+        return payload
+
+    def __iter__(self) -> Generator[GeneralManagerType, None, None]:
+        for key in self._matching_keys():
+            yield self._manager_class(**{self._interface_cls.excel_meta.key: key})
+
+    def filter(self, **kwargs: Any) -> ExcelBucket[GeneralManagerType]:
+        """Return a bucket narrowed to rows matching every lookup."""
+        constraints = self._normalize_reserved_constraints(kwargs)
+        self._validate_lookups(lookup for lookup, _expected in constraints)
+        return ExcelBucket(
+            self._manager_class,
+            self._interface_cls,
+            filters=(*self._filters, *constraints),
+            excludes=self._excludes,
+            keys=self._keys,
+        )
+
+    def exclude(self, **kwargs: Any) -> ExcelBucket[GeneralManagerType]:
+        """Return a bucket without rows matching any supplied lookup."""
+        constraints = self._normalize_reserved_constraints(kwargs)
+        self._validate_lookups(lookup for lookup, _expected in constraints)
+        return ExcelBucket(
+            self._manager_class,
+            self._interface_cls,
+            filters=self._filters,
+            excludes=(*self._excludes, *constraints),
+            keys=self._keys,
+        )
+
+    def all(self) -> ExcelBucket[GeneralManagerType]:
+        """Return an independent bucket preserving the current query."""
+        return ExcelBucket(
+            self._manager_class,
+            self._interface_cls,
+            filters=self._filters,
+            excludes=self._excludes,
+            keys=self._keys,
+        )
+
+    def count(self) -> int:
+        """Return the number of rows in the current query."""
+        return len(self._matching_keys())
+
+    def first(self) -> GeneralManagerType | None:
+        """Return the first matching manager, or ``None`` when empty."""
+        items = tuple(self)
+        return items[0] if items else None
+
+    def last(self) -> GeneralManagerType | None:
+        """Return the last matching manager, or ``None`` when empty."""
+        items = tuple(self)
+        return items[-1] if items else None
+
+    def get(self, **kwargs: Any) -> GeneralManagerType:
+        """Return the single matching manager or raise when the count differs."""
+        bucket = self.filter(**kwargs) if kwargs else self
+        items = tuple(bucket)
+        if len(items) != 1:
+            raise ExcelSingleItemRequiredError()
+        return items[0]
+
+    def __getitem__(
+        self,
+        item: int | slice,
+    ) -> GeneralManagerType | ExcelBucket[GeneralManagerType]:
+        keys = self._matching_keys()
+        if isinstance(item, slice):
+            return ExcelBucket(
+                self._manager_class,
+                self._interface_cls,
+                keys=keys[item],
+            )
+        return self._manager_class(**{self._interface_cls.excel_meta.key: keys[item]})
+
+    def __len__(self) -> int:
+        return self.count()
+
+    def __contains__(self, item: GeneralManagerType) -> bool:
+        key = item.identification[self._interface_cls.excel_meta.key]
+        return key in set(self._matching_keys())
+
+    def __or__(
+        self,
+        other: Bucket[GeneralManagerType] | GeneralManagerType,
+    ) -> ExcelBucket[GeneralManagerType]:
+        keys = list(self._matching_keys())
+        if isinstance(other, ExcelBucket):
+            if (
+                other._manager_class is not self._manager_class
+                or other._interface_cls is not self._interface_cls
+            ):
+                raise ExcelBucketUnionError(
+                    self._manager_class,
+                    other,
+                    other_manager_class=other._manager_class,
+                )
+            keys.extend(other._matching_keys())
+        elif isinstance(other, self._manager_class):
+            keys.append(other.identification[self._interface_cls.excel_meta.key])
+        else:
+            raise ExcelBucketUnionError(self._manager_class, other)
+        return ExcelBucket(
+            self._manager_class,
+            self._interface_cls,
+            keys=tuple(dict.fromkeys(keys)),
+        )
+
+    def sort(
+        self,
+        key: tuple[str, ...] | str,
+        reverse: bool = False,
+    ) -> ExcelBucket[GeneralManagerType]:
+        """Return a bucket ordered by one or more Excel field names."""
+        key_names = (key,) if isinstance(key, str) else key
+        self._validate_field_names(key_names)
+        rows = self._matching_rows()
+        rows.sort(
+            key=lambda row: tuple(row.values[name] for name in key_names),
+            reverse=reverse,
+        )
+        return ExcelBucket(
+            self._manager_class,
+            self._interface_cls,
+            keys=tuple(row.key for row in rows),
+        )
+
+    def none(self) -> ExcelBucket[GeneralManagerType]:
+        """Return an empty bucket for this manager and interface."""
+        return ExcelBucket(self._manager_class, self._interface_cls, keys=tuple())
+
+    def _matching_rows(self) -> list[Any]:
+        self._validate_constraints()
+        self._track_dependencies()
+        self._interface_cls.sync_from_excel()
+        mirror = DEFAULT_EXCEL_STORE.mirror_for(cast(type, self._interface_cls))
+        rows = list(mirror.rows.values())
+        if self._keys is not None:
+            rows = [mirror.rows[key] for key in self._keys if key in mirror.rows]
+        for lookup, expected in self._filters:
+            matcher = create_filter_function(lookup, expected)
+            rows = [row for row in rows if matcher(_ExcelRowView(row.values))]
+        for lookup, expected in self._excludes:
+            matcher = create_filter_function(lookup, expected)
+            rows = [row for row in rows if not matcher(_ExcelRowView(row.values))]
+        return rows
+
+    def _matching_keys(self) -> tuple[Any, ...]:
+        return tuple(row.key for row in self._matching_rows())
+
+    def _validate_constraints(self) -> None:
+        self._validate_lookups(
+            lookup for lookup, _expected in (*self._filters, *self._excludes)
+        )
+
+    def _normalize_reserved_constraints(
+        self,
+        constraints: Mapping[str, Any] | Iterable[tuple[str, Any]] | None,
+    ) -> tuple[tuple[str, Any], ...]:
+        key = self._interface_cls.excel_meta.key
+        normalized: list[tuple[str, Any]] = []
+        for lookup, expected in self._normalize_constraints(constraints):
+            if lookup == "id__in":
+                lookup = f"{key}__in"
+                expected = [
+                    item[key] if isinstance(item, Mapping) else item
+                    for item in expected
+                ]
+            normalized.append((lookup, expected))
+        return tuple(normalized)
+
+    def _validate_lookups(self, lookups: Iterable[str]) -> None:
+        for lookup in lookups:
+            field_name = self._field_name_for_lookup(lookup)
+            if field_name not in self._interface_cls.excel_fields:
+                raise ExcelBucketLookupError(self._manager_class, lookup)
+
+    def _validate_field_names(self, field_names: Iterable[str]) -> None:
+        for field_name in field_names:
+            if field_name not in self._interface_cls.excel_fields:
+                raise ExcelBucketLookupError(self._manager_class, field_name)
+
+    def _field_name_for_lookup(self, lookup: str) -> str:
+        parts = lookup.split("__")
+        if len(parts) == 1:
+            return lookup
+        if len(parts) == 2 and parts[-1] in SUPPORTED_EXCEL_LOOKUPS:
+            return parts[0]
+        raise ExcelBucketLookupError(self._manager_class, lookup)
+
+    def _track_dependencies(self) -> None:
+        manager_name = self._manager_class.__name__
+        if self._filters:
+            for constraint in self._filters:
+                DependencyTracker.track(
+                    manager_name,
+                    "filter",
+                    serialize_dependency_identifier(
+                        self._dependency_payload((constraint,))
+                    ),
+                )
+        else:
+            DependencyTracker.track(manager_name, "all", "")
+        if self._excludes:
+            for constraint in self._excludes:
+                DependencyTracker.track(
+                    manager_name,
+                    "exclude",
+                    serialize_dependency_identifier(
+                        self._dependency_payload((constraint,))
+                    ),
+                )