cognick 0.0.1__py3-none-any.whl

cognick/caching.py

@@ -0,0 +1,27 @@
+import json
+import redis
+from django.conf import settings
+
+redis_host = settings.REDIS_HOST
+redis_port = settings.REDIS_PORT
+redis_select_db = settings.REDIS_SELECT_DB
+
+class RedisCache:
+    def __init__(self):
+        self.client = redis.Redis(
+            host=redis_host,
+            port=redis_port,
+            db=redis_select_db,
+            decode_responses=True
+        )
+
+    def get_data(self, cache_key):
+        data = self.client.get(cache_key)
+        return json.loads(data) if data else None
+
+    def set_data(self, cache_key, data, timeout=3600):
+        self.client.set(
+            cache_key,
+            json.dumps(data),
+            ex=timeout
+        )

cognick/cognitive/client.py

@@ -0,0 +1,84 @@
+from typing import Any
+
+import requests
+from django.conf import settings
+
+from .exceptions import (
+    CognitiveConnectionException,
+    CognitiveNotFoundException,
+    CognitiveResponseException
+)
+from .objects import CognitiveParameter
+
+
+class CognitiveClient:
+    """
+    Client for communicating with the cognitive service.
+    """
+
+    def __init__(
+        self,
+        timeout: int | None = None,
+        headers: dict[str, str] | None = None,
+    ):
+        self.url = self._get_url()
+        self.timeout = timeout or getattr(
+            settings,
+            "COGNICK_COGNITIVE_TIMEOUT",
+            10,
+        )
+        self.headers = headers or {}
+
+    @staticmethod
+    def _get_url() -> str:
+        url = getattr(
+            settings,
+            "COGNICK_COGNITIVE_URL",
+            None,
+        )
+
+        if not url:
+            raise ValueError(
+                "COGNICK_COGNITIVE_BASE_URL must be configured "
+                "in Django settings."
+            )
+
+        return url.rstrip("/")
+
+    def get_parameter(
+        self
+    ) -> CognitiveParameter:
+        url = (
+            f"{self.url}/"
+        )
+
+        try:
+            response = requests.get(
+                url,
+                headers=self.headers,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise CognitiveConnectionException(
+                f"Could not connect to cognitive service: {exc}"
+            ) from exc
+
+        if response.status_code == 404:
+            raise CognitiveNotFoundException(
+                f"Cognitive parameter was not found."
+            )
+
+        if not response.ok:
+            raise CognitiveResponseException(
+                f"Cognitive service returned status "
+                f"{response.status_code}."
+            )
+
+        try:
+            data: dict[str, Any] = response.json()
+        except ValueError as exc:
+            raise CognitiveResponseException(
+                "Cognitive service returned invalid JSON."
+            ) from exc
+
+        return CognitiveParameter(data)

cognick/cognitive/exceptions.py

@@ -0,0 +1,15 @@
+
+class CognitiveException(Exception):
+    """Base exception for cognitive package."""
+
+
+class CognitiveNotFoundException(CognitiveException):
+    """Raised when a cognitive parameter cannot be found."""
+
+
+class CognitiveConnectionException(CognitiveException):
+    """Raised when the cognitive service cannot be reached."""
+
+
+class CognitiveResponseException(CognitiveException):
+    """Raised when the cognitive service returns an invalid response."""

cognick/cognitive/fields.py

@@ -0,0 +1,317 @@
+from typing import Any
+
+from django.contrib.postgres.fields import ArrayField
+from django.db import models
+
+from .utils import get_all_data
+from .objects import CognitiveParameter
+
+
+class CognitiveFieldDescriptor:
+    """
+    Lazily resolves a cognitive parameter ID to a CognitiveParameter object.
+    """
+
+    def __init__(self, field):
+        self.field = field
+        self.attname = field.attname
+
+    def __get__(self, instance, owner=None):
+        if instance is None:
+            return self
+
+        value = instance.__dict__.get(self.attname)
+
+        if value is None:
+            return None
+
+        if isinstance(value, CognitiveParameter):
+            return value
+
+        cognitive = self.field.get_full_data(value)
+
+        instance.__dict__[self.attname] = cognitive
+
+        return cognitive
+
+    def __set__(self, instance, value):
+        instance.__dict__[self.attname] = value
+
+
+class CognitiveArrayFieldDescriptor:
+    """
+    Lazily resolves cognitive parameter IDs to CognitiveParameter objects.
+    """
+
+    def __init__(self, field):
+        self.field = field
+        self.attname = field.attname
+
+    def __get__(self, instance, owner=None):
+        if instance is None:
+            return self
+
+        value = instance.__dict__.get(self.attname)
+
+        if value is None:
+            return None
+
+        if not isinstance(value, (list, tuple)):
+            return value
+
+        if all(
+            isinstance(item, CognitiveParameter)
+            for item in value
+        ):
+            return value
+
+        resolved = self.field.get_full_data_many(value)
+
+        instance.__dict__[self.attname] = resolved
+
+        return resolved
+
+    def __set__(self, instance, value):
+        instance.__dict__[self.attname] = value
+
+
+class CognitiveField(models.CharField):
+    """
+    Stores a cognitive parameter ID in the database.
+
+    The field accepts either a cognitive parameter ID or a
+    CognitiveParameter instance when saving.
+    """
+
+    descriptor_class = CognitiveFieldDescriptor
+
+    def __init__(
+        self,
+        *args,
+        cache_timeout: int | None = None,
+        timeout: int | None = None,
+        **kwargs,
+    ):
+        kwargs.setdefault("max_length", 36)
+
+        self.cache_timeout = cache_timeout
+        self.timeout = timeout
+
+        super().__init__(*args, **kwargs)
+
+    def get_prep_value(
+        self,
+        value: CognitiveParameter | str | int | None,
+    ) -> str | None:
+        if value is None:
+            return None
+
+        if isinstance(value, CognitiveParameter):
+            return str(value.id)
+
+        if isinstance(value, (str, int)):
+            return str(value)
+
+        raise ValueError(
+            "CognitiveField only accepts a cognitive parameter ID "
+            "or a CognitiveParameter instance."
+        )
+
+    def from_db_value(
+        self,
+        value: Any,
+        expression,
+        connection,
+    ) -> str | None:
+        if value is None:
+            return None
+
+        return str(value)
+
+
+    def get_full_data(
+        self,
+        value: str | int | CognitiveParameter | None,
+    ) -> CognitiveParameter | None:
+        """
+        Resolve a cognitive parameter ID to a CognitiveParameter object.
+        """
+
+        if value is None:
+            return None
+
+        if isinstance(value, CognitiveParameter):
+            return value
+
+        value = str(value)
+
+        cognitive_data = get_all_data(
+            self.cache_timeout,
+            self.timeout
+        )
+
+        data = cognitive_data.get(value)
+
+        if data is None:
+            raise ValueError(
+                f"Cognitive parameter with ID '{value}' was not found."
+            )
+
+        return CognitiveParameter(data)
+
+    def get_full_data_many(
+        self,
+        values: list[str | int | CognitiveParameter] | tuple,
+    ) -> list[CognitiveParameter]:
+        """
+        Resolve multiple cognitive parameter IDs using the shared cache.
+        """
+
+        if not values:
+            return []
+
+        cognitive_data = get_all_data(
+            self.cache_timeout,
+            self.timeout
+        )
+
+        resolved = []
+
+        for value in values:
+            if isinstance(value, CognitiveParameter):
+                resolved.append(value)
+                continue
+
+            value = str(value)
+
+            data = cognitive_data.get(value)
+
+            if data is None:
+                raise ValueError(
+                    f"Cognitive parameter with ID '{value}' was not found."
+                )
+
+            resolved.append(
+                CognitiveParameter(data)
+            )
+
+        return resolved
+
+
+class CognitiveArrayField(ArrayField):
+    """
+    Stores a list of cognitive parameter IDs in the database.
+
+    Values are stored as IDs and lazily resolved to CognitiveParameter
+    objects when the model attribute is accessed.
+    """
+
+    descriptor_class = CognitiveArrayFieldDescriptor
+
+    def __init__(
+        self,
+        base_field=None,
+        *args,
+        cache_timeout: int | None = None,
+        timeout: int | None = None,
+        **kwargs,
+    ):
+        self.cache_timeout = cache_timeout
+        self.timeout = timeout
+
+        if base_field is None:
+            base_field = CognitiveField(
+                cache_timeout=cache_timeout,
+                timeout=timeout,
+            )
+
+        super().__init__(
+            base_field=base_field,
+            *args,
+            **kwargs,
+        )
+
+    def get_full_data(
+        self,
+        value: str | int | CognitiveParameter | None,
+    ) -> CognitiveParameter | None:
+        """
+        Resolve a cognitive parameter ID to a CognitiveParameter object.
+        """
+
+        if value is None:
+            return None
+
+        if isinstance(value, CognitiveParameter):
+            return value
+
+        if isinstance(self.base_field, CognitiveField):
+            return self.base_field.get_full_data(value)
+
+        cognitive_field = CognitiveField(
+            cache_timeout=self.cache_timeout,
+            timeout=self.timeout,
+        )
+
+        return cognitive_field.get_full_data(value)
+
+    def get_full_data_many(
+        self,
+        values: list[str | int | CognitiveParameter] | tuple,
+    ) -> list[CognitiveParameter]:
+        """
+        Resolve multiple cognitive parameter IDs using the shared cache.
+        """
+
+        if not values:
+            return []
+
+        if isinstance(self.base_field, CognitiveField):
+            return self.base_field.get_full_data_many(values)
+
+        cognitive_field = CognitiveField(
+            cache_timeout=self.cache_timeout,
+            timeout=self.timeout,
+        )
+
+        return cognitive_field.get_full_data_many(values)
+
+    def get_prep_value(
+        self,
+        value: Any,
+    ) -> list[str] | None:
+        """
+        Prepare cognitive parameter values for database storage.
+        """
+
+        if value is None:
+            return None
+
+        if not isinstance(value, (list, tuple)):
+            raise ValueError(
+                "CognitiveArrayField only accepts a list or tuple."
+            )
+
+        return [
+            self.get_prep_value_item(item)
+            for item in value
+        ]
+
+    def get_prep_value_item(
+        self,
+        value: str | int | CognitiveParameter,
+    ) -> str:
+        """
+        Prepare a single cognitive parameter value for database storage.
+        """
+
+        if isinstance(value, CognitiveParameter):
+            return str(value.id)
+
+        if isinstance(value, (str, int)):
+            return str(value)
+
+        raise ValueError(
+            "CognitiveArrayField items must be cognitive parameter IDs "
+            "or CognitiveParameter instances."
+        )

cognick/cognitive/objects.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+
+class CognitiveParameter:
+    """
+    Represents a cognitive parameter retrieved from the cognitive service.
+    """
+
+    def __init__(self, payload: dict[str, Any]):
+        self._payload = payload
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self._payload[name]
+        except KeyError as exc:
+            raise AttributeError(
+                f"{self.__class__.__name__!s} object has no attribute {name!r}"
+            ) from exc
+
+    def __getitem__(self, key: str) -> Any:
+        return self._payload[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._payload.get(key, default)
+
+    @property
+    def payload(self) -> dict[str, Any]:
+        return self._payload
+
+    @property
+    def id(self) -> str | int | None:
+        return self._payload.get("id")
+
+    def __bool__(self) -> bool:
+        return bool(self._payload)
+
+    def __repr__(self) -> str:
+        return f"<CognitiveParameter(id={self.id})>"

cognick/cognitive/serializers.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from rest_framework import serializers
+from .objects import CognitiveParameter
+
+
+class CognitiveParameterSerializer(serializers.Serializer):
+    """
+    Dynamically serializes a CognitiveParameter payload.
+    """
+
+    def to_representation(self, instance: CognitiveParameter) -> dict[str, Any]:
+        if isinstance(instance, CognitiveParameter):
+            return instance.payload.copy()
+
+        if isinstance(instance, dict):
+            return instance.copy()
+
+        return super().to_representation(instance)

cognick/cognitive/utils.py

@@ -0,0 +1,67 @@
+from typing import Any
+from django.conf import settings
+
+from caching import RedisCache
+from .client import CognitiveClient
+
+
+
+def get_all_data(
+        cache_timeout,
+        timeout
+) -> dict[str, dict[str, Any]]:
+    """
+    Get all cognitive parameters indexed by their ID.
+
+    The complete list is cached so individual cognitive parameter
+    lookups do not require separate API requests.
+    """
+    all_cache_key = "cognick:cognitive:all"
+
+    cache = RedisCache()
+    cached_data = cache.get_data(all_cache_key)
+
+    if cached_data is not None:
+        return cached_data
+
+    client = CognitiveClient(
+        timeout=timeout,
+    )
+
+    response = client.get_parameter()
+
+    data = response.payload
+
+    if isinstance(data, dict):
+        parameters = data.get("results", data.get("data", []))
+    else:
+        parameters = data
+
+    if not isinstance(parameters, list):
+        raise ValueError(
+            "Cognitive API returned an invalid response format."
+        )
+
+    cognitive_data = {
+        str(item["id"]): item
+        for item in parameters
+        if isinstance(item, dict) and item.get("id") is not None
+    }
+
+    cache_timeout = (
+        cache_timeout
+        if cache_timeout is not None
+        else getattr(
+            settings,
+            "COGNICK_COGNITIVE_CACHE_TIMEOUT",
+            3600,
+        )
+    )
+
+    cache.set_data(
+        all_cache_key,
+        cognitive_data,
+        timeout=cache_timeout,
+    )
+
+    return cognitive_data