base-api-utils 1.1.93__tar.gz → 1.1.95__tar.gz

{base_api_utils-1.1.93/src/base_api_utils.egg-info → base_api_utils-1.1.95}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: base-api-utils
-Version: 1.1.93
+Version: 1.1.95
 Summary: Django Rest Framework micro services common utilities
 Author-email: Román Gutierrez <roman@tipit.net>, Sebastian Marcet <sebastian@tipit.net>
 Project-URL: Homepage, https://github.com/fntechgit/base-api-utils

{base_api_utils-1.1.93 → base_api_utils-1.1.95}/pyproject.toml

@@ -7,7 +7,7 @@ where = ["src"]
 
 [project]
 name = "base-api-utils"
-version = "1.1.93"
+version = "1.1.95"
 dependencies = [
     "boto3",
     "celery",

{base_api_utils-1.1.93 → base_api_utils-1.1.95}/src/base_api_utils/serializers/v2/expands.py

@@ -13,6 +13,7 @@ class ExpandMapping:
     original_attribute: str | None = None
     source: str | None = None
     verify_relation: bool = False
+    schema_override: type | None = None
 
     @property
     def source_kwargs(self) -> dict:
@@ -86,6 +87,17 @@ class One2ManyExpandSerializer(IExpandSerializer):
                 fields[fk] = serializers.IntegerField(read_only=True)
 
 
+class _IDListField(serializers.Field):
+    """Runtime: returns list of PKs. Schema: annotated externally via _spectacular_annotation."""
+    def to_representation(self, value):
+        if hasattr(value, 'all'):
+            return [item.pk for item in value.all()]
+        return [item.pk for item in value]
+
+    def to_internal_value(self, data):
+        return data
+
+
 class Many2OneExpandSerializer(IExpandSerializer):
     # to-many: keep same key; not expanded => list[int]; expanded => list[object]
     def apply(self, *, fields: dict, mapping: ExpandMapping, context: dict) -> None:
@@ -115,8 +127,7 @@ class Many2OneExpandSerializer(IExpandSerializer):
                 **mapping.source_kwargs,
             )
         else:
-            fields[attr] = serializers.PrimaryKeyRelatedField(
-                many=True,
-                read_only=True,
-                **mapping.source_kwargs,
-            )
+            schema_cls = mapping.schema_override or mapping.serializer
+            id_field = _IDListField(read_only=True, **mapping.source_kwargs)
+            id_field._spectacular_annotation = {"field": schema_cls(many=True, read_only=True)}
+            fields[attr] = id_field

base_api_utils-1.1.95/src/base_api_utils/utils/fingerprint_helpers.py

@@ -0,0 +1,190 @@
+"""
+1 - Fingerprint utility functions for computing SHA-256 based identity hashes.
+
+These functions enable change detection to determine when entities need to be
+created or updated by computing deterministic fingerprints from their field values.
+
+2 - FingerPrintMixin to centralize models fingerprint generation.
+"""
+
+import hashlib
+from datetime import datetime
+from typing import Any, Dict, Iterable, Optional
+
+
+def compute_sha256(data: str) -> str:
+    """
+    Compute SHA-256 hash of the input string.
+
+    Args:
+        data: The string to hash
+
+    Returns:
+        64-character lowercase hex string
+    """
+    return hashlib.sha256(data.encode('utf-8')).hexdigest()
+
+
+def format_value(value: Any) -> Optional[str]:
+    """
+    Format a field value for inclusion in a fingerprint string.
+
+    Args:
+        value: The value to format
+
+    Returns:
+        Formatted string representation, or None if the value should be skipped
+    """
+    if value is None:
+        return None
+
+    if isinstance(value, bool):
+        return "true" if value else "false"
+
+    if isinstance(value, datetime):
+        return value.isoformat()
+
+    return str(value)
+
+
+def build_fingerprint_string(fields: Dict[str, Any]) -> str:
+    """
+    Build a deterministic string from field name-value pairs.
+
+    Fields are sorted by name for determinism. Fields with None values are skipped.
+
+    Args:
+        fields: Dictionary of field names to values
+
+    Returns:
+        Concatenated string of "name=value" pairs separated by "|"
+    """
+    parts = []
+    for key in sorted(fields.keys()):
+        formatted = format_value(fields[key])
+        if formatted is not None:
+            parts.append(f"{key}={formatted}")
+    return "|".join(parts)
+
+
+def format_id_list(ids: Iterable[int]) -> str:
+    """
+    Format a list of IDs as a comma-separated string.
+
+    IDs are sorted numerically for determinism.
+
+    Args:
+        ids: Iterable of integer IDs
+
+    Returns:
+        Comma-separated string of sorted IDs
+    """
+    return ",".join(str(id_) for id_ in sorted(ids))
+
+
+def combine_fingerprints(fingerprints: Iterable[str]) -> str:
+    """
+    Combine multiple fingerprints into a single hash.
+
+    Fingerprints are sorted for determinism before being concatenated and hashed.
+
+    Args:
+        fingerprints: Iterable of fingerprint hex strings
+
+    Returns:
+        64-character lowercase hex string, or empty string if no fingerprints
+    """
+    sorted_fps = sorted(fingerprints)
+    if not sorted_fps:
+        return ""
+    combined = "|".join(sorted_fps)
+    return compute_sha256(combined)
+
+
+class FingerPrintMixin:
+    def _get_base_fingerprint_fields(self) -> dict:
+        return {}
+
+    def _get_specific_fingerprint_fields(self) -> dict:
+        return {}
+
+    def _get_m2m_fingerprint_fields(self) -> dict:
+        return {}
+
+    def _get_base_m2m_fields(self) -> dict:
+        return {}
+
+    def _get_children_accessors(self) -> list[dict]:
+        """
+        Returns a list of child descriptor dicts, each with:
+          - 'accessor':  the related manager name as a string (e.g. 'meta_fields')
+          - 'order_by':  field name used to sort the collection (e.g. 'id')
+
+        Subclasses should override this to declare their child relations.
+        Example:
+            return [{'accessor': 'meta_fields', 'order_by': 'id'}]
+        """
+        return []
+
+    def _resolve_children(self, accessor: str, order_by: str) -> list:
+        """
+        Resolves a child collection respecting three possible sources,
+        in priority order:
+
+        1. In-memory prefetch cache (_prefetched_objects_cache) — avoids DB hits
+           when objects have been built or prefetched outside the ORM.
+        2. Database query via the related manager — only when the instance
+           has already been persisted (pk is set).
+        3. Empty list — for unsaved instances with no prefetched data.
+        """
+        cache = getattr(self, '_prefetched_objects_cache', {})
+
+        if accessor in cache:
+            # Sort in-memory using the order_by field (strip leading '-' for reverse)
+            reverse = order_by.startswith('-')
+            field = order_by.lstrip('-')
+            return sorted(cache[accessor], key=lambda x: getattr(x, field), reverse=reverse)
+
+        if self.pk:
+            return list(getattr(self, accessor).all().order_by(order_by))
+
+        return []
+
+    def _compute_own_fingerprint(self, field_overrides=None) -> str:
+        all_fields = {
+            **self._get_base_fingerprint_fields(),
+            **self._get_specific_fingerprint_fields(),
+        }
+
+        # Append M2M relation IDs as formatted strings
+        for key, id_list in self._get_m2m_fingerprint_fields().items():
+            if id_list:
+                all_fields[key] = format_id_list(id_list)
+
+        # Allow caller to substitute values without mutating the instance
+        if field_overrides:
+            all_fields.update(field_overrides)
+
+        return compute_sha256(build_fingerprint_string(all_fields))
+
+    def fingerprint(self, field_overrides=None) -> str:
+
+        # 1. Compute this instance's own hash
+        own_hash = self._compute_own_fingerprint(field_overrides)
+
+        # 2. Recursively collect hashes from each child collection
+        children_hashes = []
+        for descriptor in self._get_children_accessors():
+            children = self._resolve_children(
+                accessor=descriptor['accessor'],
+                order_by=descriptor['order_by'],
+            )
+            for child in children:
+                children_hashes.append(child.fingerprint())
+
+        # 3. Combine own hash with children hashes into a single fingerprint
+        if children_hashes:
+            combined = combine_fingerprints(children_hashes)
+            return compute_sha256(f"{own_hash}|{combined}")
+
+        return own_hash

{base_api_utils-1.1.93 → base_api_utils-1.1.95/src/base_api_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: base-api-utils
-Version: 1.1.93
+Version: 1.1.95
 Summary: Django Rest Framework micro services common utilities
 Author-email: Román Gutierrez <roman@tipit.net>, Sebastian Marcet <sebastian@tipit.net>
 Project-URL: Homepage, https://github.com/fntechgit/base-api-utils

base_api_utils-1.1.93/src/base_api_utils/utils/fingerprint_helpers.py

@@ -1,99 +0,0 @@
-"""
-Fingerprint utility functions for computing SHA-256 based identity hashes.
-
-These functions enable change detection to determine when entities need to be
-created or updated by computing deterministic fingerprints from their field values.
-"""
-
-import hashlib
-from datetime import datetime
-from typing import Any, Dict, Iterable, Optional
-
-
-def compute_sha256(data: str) -> str:
-    """
-    Compute SHA-256 hash of the input string.
-
-    Args:
-        data: The string to hash
-
-    Returns:
-        64-character lowercase hex string
-    """
-    return hashlib.sha256(data.encode('utf-8')).hexdigest()
-
-
-def format_value(value: Any) -> Optional[str]:
-    """
-    Format a field value for inclusion in a fingerprint string.
-
-    Args:
-        value: The value to format
-
-    Returns:
-        Formatted string representation, or None if the value should be skipped
-    """
-    if value is None:
-        return None
-
-    if isinstance(value, bool):
-        return "true" if value else "false"
-
-    if isinstance(value, datetime):
-        return value.isoformat()
-
-    return str(value)
-
-
-def build_fingerprint_string(fields: Dict[str, Any]) -> str:
-    """
-    Build a deterministic string from field name-value pairs.
-
-    Fields are sorted by name for determinism. Fields with None values are skipped.
-
-    Args:
-        fields: Dictionary of field names to values
-
-    Returns:
-        Concatenated string of "name=value" pairs separated by "|"
-    """
-    parts = []
-    for key in sorted(fields.keys()):
-        formatted = format_value(fields[key])
-        if formatted is not None:
-            parts.append(f"{key}={formatted}")
-    return "|".join(parts)
-
-
-def format_id_list(ids: Iterable[int]) -> str:
-    """
-    Format a list of IDs as a comma-separated string.
-
-    IDs are sorted numerically for determinism.
-
-    Args:
-        ids: Iterable of integer IDs
-
-    Returns:
-        Comma-separated string of sorted IDs
-    """
-    return ",".join(str(id_) for id_ in sorted(ids))
-
-
-def combine_fingerprints(fingerprints: Iterable[str]) -> str:
-    """
-    Combine multiple fingerprints into a single hash.
-
-    Fingerprints are sorted for determinism before being concatenated and hashed.
-
-    Args:
-        fingerprints: Iterable of fingerprint hex strings
-
-    Returns:
-        64-character lowercase hex string, or empty string if no fingerprints
-    """
-    sorted_fps = sorted(fingerprints)
-    if not sorted_fps:
-        return ""
-    combined = "|".join(sorted_fps)
-    return compute_sha256(combined)