django-structured-json-field 1.6.0__py3-none-any.whl

django_structured_json_field-1.6.0.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: django-structured-json-field
+Version: 1.6.0
+Summary: Django json field empowered by pydantic
+Author-email: Lotrèk <gabriele@lotrek.it>
+License: MIT
+Project-URL: Homepage, https://github.com/lotrekagency/django-structured-json-field
+Keywords: django,pydantic,django pydantic,django json,json schema,django form
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: djangorestframework<4.0.0,>=3.14.0
+Requires-Dist: Django>=4.2
+Requires-Dist: pydantic>=2.12
+Dynamic: license-file
+
+# Django Structured JSON Field [![PyPI](https://img.shields.io/pypi/v/django-structured-json-field?style=flat-square)](https://pypi.org/project/django-structured-json-field) ![Codecov](https://img.shields.io/codecov/c/github/bnznamco/django-structured-field?style=flat-square&logo=codecov&logoSize=auto&cacheSeconds=0) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/lotrekagency/django-structured-field/ci.yml?style=flat-square) [![GitHub](https://img.shields.io/github/license/lotrekagency/django-structured-field?style=flat-square)](./LICENSE) [![Docs](https://img.shields.io/badge/docs-online-brightgreen?style=flat-square)](https://bnznamco.github.io/django-structured-field/)
+
+
+<br>
+<br>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/.vuepress/public/images/logo-dark.svg" width="200">
+    <source media="(prefers-color-scheme: light)" srcset="docs/.vuepress/public/images/logo.svg" width="200">
+    <img alt="Django Structured JSON Field logo" src="docs/.vuepress/public/images/logo.svg" width="200">
+  </picture>
+</p>
+<br>
+<br>
+<br>
+<br>
+
+
+
+This is a Django field that allows you to declare the structure of a JSON field and validate it.
+
+## Features
+
+- Define the structure of a JSON field using Pydantic models
+- Validate the JSON field against the defined structure
+- Use relationships between models inside the JSON field 🤯
+- Django-native `prefetch_related` across JSON paths — `MyModel.objects.prefetch_related("structured_data__author__country")` Just Works 🚀
+- Easily integrate with Django Rest Framework serializers
+- Admin editor for the JSON field with autocomplete search for related models 👀
+
+
+## Documentation
+
+Check out our [documentation](https://bnznamco.github.io/django-structured-field/) for detailed guides and examples on:
+
+- Installation and basic usage
+- Working with relationships
+- Prefetching relations across JSON paths
+- Admin integration
+- REST Framework integration
+- Caching
+- Settings configuration
+
+
+
+## Installation
+
+```bash
+pip install django-structured-json-field
+```
+
+## Usage
+
+```python
+from django.db import models
+from structured.fields import StructuredJSONField
+from structured.pydantic.models import BaseModel
+
+# Define this schema as you would do with a Pydantic model
+class MySchema(BaseModel):
+    name: str
+    age: int = None
+
+def init_data():
+    return MySchema(name='')
+
+# Create a model with a StructuredJSONField with the schema you defined
+class MyModel(models.Model):
+    structured_data = StructuredJSONField(schema=MySchema, default=init_data)
+
+```
+
+## Relationships
+
+This field supports relationships between models, you can define them in your schema and they will be treated as normal django relationships. It also supports recursive schemas.
+
+### Recursion
+
+You can define recursive schemas by declaring the attribute type as a string:
+
+```python
+from typing import Optional, List
+
+class MySchema(BaseModel):
+    name: str
+    age: int = None
+    parent: Optional['MySchema'] = None
+    relateds: List['MySchema'] = []
+```
+
+### Foreign Keys
+
+You can also define model relationships in your schema:
+
+```python
+from structured.pydantic.fields import ForeignKey
+
+class MySchema(BaseModel):
+    name: str
+    age: int = None
+    fk_field: ForeignKey['MyModel'] = None
+```
+
+This will treat the parent field as a normal django ForeignKey.
+
+#### Tip:
+
+You can omit the `ForeignKey` field and just use the model class as the type annotation:
+
+```python
+class MySchema(BaseModel):
+    name: str
+    age: int = None
+    fk_field: MyModel = None
+```
+
+the field will still be treated as a ForeignKey if the type annotation is a subclass of django `models.Model`.
+
+### ManyToMany
+
+If you need a ManyToMany relationship, you can use the `QuerySet` field:
+
+```python
+from structured.pydantic.fields import QuerySet
+
+class MySchema(BaseModel):
+    name: str
+    age: int = None
+    parents: QuerySet['MyModel']
+```
+
+`QuerySet` fields will generate a django object manager that will allow you to query the related objects as you would do with a normal django `QuerySet`.
+
+```python
+instance = MySchema(name='test', age=10, parents=MyModel.objects.all())
+# You can filter the queryset
+instance.parents.filter(name='test')
+# You can count the queryset
+instance.parents.count()
+# You can get the first element of the queryset, etc...
+instance.parents.first()
+```
+
+### Admin integration
+
+The field is integrated with the Django admin, you can use the autocomplete search to select the related models. To allow the autocomplete search you need to include structured.urls in your urls.py file:
+
+```python
+from django.urls import path, include
+
+urlpatterns = [
+    path('admin/', admin.site.urls),
+    path('', include('structured.urls')),
+]
+```
+
+### Rest Framework integration
+
+You can easily integrate structured fields with Django Rest Framework serializers, just use the `StructuredModelSerializer` as the base class for your serializer:
+
+```python
+from rest_framework import serializers
+from structured.contrib.rest_framework import StructuredModelSerializer
+
+class MyModelSerializer(StructuredModelSerializer):
+    class Meta:
+        model = MyModel
+        fields = '__all__'
+```
+
+Errors generated by pydantic validation will be automatically translated to DRF errors.
+
+
+### Cache
+
+To prevent the field from making multiple identical queries a caching technique is used. The cache is still a work in progress, please open an issue if you find any problem.
+Actually the cache covers all the relations inside a StructuredJSONField, optimizing the queries during the serialization process.
+
+#### Cache engine progress:
+
+- [x] Shared cache between `ForeignKey` fields and `QuerySet` fields
+- [x] Shared cache through nested schemas
+- [x] Shared cache through nested lists of schemas
+- [ ] Shared cache between all `StructuredJSONFields` in the same instance
+- [ ] Shared cache between multiple instances of the same model
+- [ ] Cache invalidation mechanism
+
+## Settings
+
+You can manage structured field behaviour modifying the `STRUCTURED_FIELD` setting in your `settings.py` file. Here a list of the available settings and their default values:
+
+```python
+STRUCTURED_FIELD = {
+    'CACHE':{
+        'ENABLED': True,
+        'SHARED': False # ⚠️ EXPERIMENTAL: this enables a thread-shared cache, it's not recommended to use it in production.
+    },
+}
+```
+
+## Contributing
+
+The project is open to contributions, just open an issue or a PR.
+
+### Running tests
+
+```bash
+pip install -r requirements-dev.txt
+make test
+```
+
+### Running test app
+
+```bash
+pip install -r requirements-dev.txt
+python manage.py migrate
+python manage.py runserver
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

django_structured_json_field-1.6.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+django_structured_json_field-1.6.0.dist-info/licenses/LICENSE,sha256=2_XPsmGfwHVMSsUsHX7f2lxyLluSjm7RcRlnd7iaP3c,1074
+structured/__init__.py,sha256=DXEWnP5eZfUwa3rzzQ_vPP3po5wQtMqyeA2vat6xIkw,227
+structured/apps.py,sha256=pUQi2lciJdIYwUXXoP3FTrUU2DdyCjL6QinNI8__c78,136
+structured/fields.py,sha256=Va93mv5YhfwsEJ7Bhok0Jw__ovp1k2onyWlb6H2oMpk,10334
+structured/orm.py,sha256=8GVCRdGfjQ_EGQJqQuby9heoOSpjPXt7kw1dNDGjpV0,24513
+structured/settings.py,sha256=YlH3fwjs8eYawv0hILH3IHUgRXdA6a41qu-chKnxCTw,1067
+structured/urls.py,sha256=TbwHE2n6v5XaHBmo1d7OWEXtOdIQFibGFVAALZhFJVw,173
+structured/views.py,sha256=urNvjwurbcnRhGUJ8lGJGiNWaTjbN4pPU_StsQ6AfnY,3082
+structured/cache/__init__.py,sha256=8xQBYjkgFVH9Bytgj5OAyBCRdCweHuwk6KiJeunWX4g,262
+structured/cache/cache.py,sha256=Y4MhFYT57e-wONZi9QymD0vsuGMn8f6jUtNbHZx4N5M,8730
+structured/cache/engine.py,sha256=SLv4vMOFp6ScpKUg1wn0NMzC6lKvziyZtjrLpUaqers,14411
+structured/cache/rel_info.py,sha256=K8EEhUCufKcW4O0GQKQReG3cltNmuYRHZ_bMOwCo8Ac,606
+structured/contrib/restframework.py,sha256=A7oX2uTHg8sXeoWOicLWlE41HOvjYurLRqz3dI2KYYk,2946
+structured/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structured/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structured/management/commands/generate_schema_migration.py,sha256=ko9S1mS0VyovjprqjUPaddB69lF2sfDTs_6F3Jd52Es,6389
+structured/pydantic/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structured/pydantic/conditionals.py,sha256=GW9ZpuSaSVMEloYg9p22i-TJ49jkeT_E51YgqO1UO8U,10423
+structured/pydantic/models.py,sha256=9fMFmmJfRw0wB2cEC5dCPAAq2LBa7mC2EeCVjh5it5o,4079
+structured/pydantic/fields/__init__.py,sha256=rkDcCYYMZWro8qQWcRM_c89mstFyHlmPU2tGa11rVMg,116
+structured/pydantic/fields/foreignkey.py,sha256=_1CCBp3srU7aRPDokXiG4PPBzCVifqPDMg4zn6aPDRo,5224
+structured/pydantic/fields/queryset.py,sha256=AfT7SUkLVWWpvkRC8uB2qEpJnMkONhxA8lGRWHK7ioM,5909
+structured/pydantic/fields/serializer.py,sha256=vzEBPiY8D_oXBRVVyN0LwicTdCJaNgBLqadMokgk7_4,1655
+structured/schema_migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structured/schema_migrations/structured_json_migration.py,sha256=5sywecUyGdWG4C7XCUWc2h_K-evr5D6NpqhptSUuW1Y,11863
+structured/static/js/structured-field-init.js,sha256=NmTFO8Rgog7rQJgC9CvWdzXJS3qrHSE2Xpo4cIzAZI8,1210
+structured/templates/json-forms/widget.html,sha256=BCIGYmtHEtmOK_u_-ojR5WOKIRihuZww6rY8kr_dEEs,535
+structured/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structured/utils/cast.py,sha256=q7E6WflY_DP2kcs-Znk7Sp2xQBwYZZWrtryT2gkPKuE,1129
+structured/utils/context.py,sha256=xwDa118xsr70eaT-zQTPBP63hmNCTeccZ8dON_fYl3s,560
+structured/utils/dict.py,sha256=RDCZtjwpEEwjvfUjQl2bEWFKw7NxTzkXco72VeO2M9w,255
+structured/utils/django.py,sha256=cZjXnsQ-kQa18xzQ7BwZnsq_oM39ZgJF4HgZCw_cwUA,1345
+structured/utils/errors.py,sha256=Mh-I9n1FpWr94Ry6LcqJCqOKgSUJXB_PmYASmuL869g,1366
+structured/utils/getter.py,sha256=NrlByyd4SrFp3aVpdA21MMs3bcJFyequsxoIkrh7ATI,639
+structured/utils/namespace.py,sha256=Pe3DmUryy8YWkI-fAuxV9cPH6AWEaYI1u9h3p_3CZkU,892
+structured/utils/options.py,sha256=6GJpHc2R31gKNue8TC9hDcfgJnJQvcdriyx93TWxDo0,1037
+structured/utils/pydantic.py,sha256=M73wr0dyyAmtE-3ZG8NywfBA0xXjoip_T1xmJw9d1b4,3526
+structured/utils/replace.py,sha256=0pHmKCZhUBLUeUIv2OD3qces2yYhNOSXoNUNPk3iCzA,436
+structured/utils/serializer.py,sha256=NEVsQLkNP7S0kW8ze26bzjhUBWEVspCznuHG8u1F4Fk,3836
+structured/utils/setter.py,sha256=6iF3gG8RfatxBYeubU1KweP48UVbS1LcnungnmqMqm8,1358
+structured/utils/typing.py,sha256=1PbRc0sy_BhT6KkYAaXkvYbzs1cCu1iSykdhvBaplek,3430
+structured/widget/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structured/widget/fields.py,sha256=Woi5R0ob4-t416gHtxCurz2vtCaN9thoRUbKICJoPts,2607
+structured/widget/widgets.py,sha256=9PYUGETpn-XbSb9bM3OYdJlUXIW9yRWBQHmSs7jOrm0,3844
+django_structured_json_field-1.6.0.dist-info/METADATA,sha256=xC13yMMhEdLiFWgmT7sCiLaz8IyIAZoCmpOPqdLTqAI,7966
+django_structured_json_field-1.6.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+django_structured_json_field-1.6.0.dist-info/top_level.txt,sha256=exTAxPKh1S71ZrY3PJ7PTnmRbnQEBRE09OPnyIpDJ28,11
+django_structured_json_field-1.6.0.dist-info/RECORD,,

django_structured_json_field-1.6.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_structured_json_field-1.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Lotrèk 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

django_structured_json_field-1.6.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+structured

structured/__init__.py

@@ -0,0 +1,13 @@
+from structured.orm import (
+    StructuredManager,
+    StructuredQuerySet,
+    StructuredQuerySetMixin,
+)
+
+__version__ = "1.6.0"
+
+__all__ = [
+    "StructuredManager",
+    "StructuredQuerySet",
+    "StructuredQuerySetMixin",
+]

structured/apps.py

@@ -0,0 +1,7 @@
+from __future__ import unicode_literals
+
+from django.apps import AppConfig
+
+
+class StructuredConfig(AppConfig):
+    name = "structured"

structured/cache/__init__.py

@@ -0,0 +1,10 @@
+from structured.cache.engine import CacheEngine, CacheEnabledModel
+from structured.cache.cache import get_global_cache, Cache, ThreadSafeCache
+
+__all__ = [
+    "CacheEngine",
+    "CacheEnabledModel",
+    "Cache",
+    "ThreadSafeCache",
+    "get_global_cache",
+]

structured/cache/cache.py

@@ -0,0 +1,257 @@
+from collections import defaultdict
+from typing import Type, Union, Iterable, Dict, Any, TYPE_CHECKING
+from django.db.models import Model as DjangoModel
+from django.db.models.query import QuerySet as DjangoQuerySet
+from django.db.models.signals import post_save, pre_delete
+from pydantic import ValidationInfo, model_validator
+import threading
+from structured.settings import settings
+
+if TYPE_CHECKING:  # pragma: no cover
+    from structured.pydantic.models import BaseModel
+    from structured.cache.engine import CacheEngine
+
+
+CACHE_CONTEXT_KEY = "structured_parent_cache"
+
+
+class CacheEnabledModel:
+    """
+    A model class that enables caching.
+
+    When validated via ``schema.validate_python(value, context={...})``,
+    a ``Cache`` instance under the ``CACHE_CONTEXT_KEY`` key is reused
+    instead of creating a fresh per-call cache — letting multiple
+    ``StructuredJSONField``s on the same Django instance share one
+    fetch pool.
+    """
+
+    _cache_engine: 'CacheEngine'
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def build_cache(
+        cls,
+        data: Dict[str, Any],
+        handler: Any,
+        info: ValidationInfo,
+    ) -> Any:
+        """
+        Build and fetch cache for the given data.
+
+        ``info`` is declared as a required positional argument with a
+        typed annotation so pydantic's signature inspection always
+        passes it. With ``info=None`` defaults, pydantic v2 sometimes
+        elects the shorter ``(cls, data, handler)`` overload and the
+        validator never sees the parent cache.
+        """
+        parent_cache = None
+        if info is not None and info.context:
+            parent_cache = info.context.get(CACHE_CONTEXT_KEY)
+        data = cls._cache_engine.build_cache(data, parent_cache=parent_cache)
+        instance: "BaseModel" = handler(data)
+        return cls._cache_engine.fetch_cache(instance)
+
+
+def get_global_cache():
+    if settings.STRUCTURED_FIELD_SHARED_CACHE:
+        return ThreadSafeCache()
+    return None
+
+
+class Cache(defaultdict):
+    """
+    The cache class that stores the cache data.
+    Per-request caches do NOT connect to Django signals — they are short-lived
+    and discarded after validation. Only ThreadSafeCache (shared mode) connects
+    signals for cross-request cache invalidation.
+    The cache data is stored in the following format:
+    {
+        Model1: {
+            pk1: instance1,
+            pk2: instance2,
+            ...
+        },
+        Model2: {
+            pk1: instance1,
+            pk2: instance2,
+            ...
+        },
+    """
+
+    def __init__(self) -> None:
+        super().__init__(dict)
+
+    def flush(
+        self, data: Union[DjangoModel, Iterable[DjangoModel], None] = None, **kwargs
+    ) -> None:
+        """
+        Flush the cache for the given data and/or model; with no arguments,
+        clear the whole cache. An empty iterable flushes nothing.
+        """
+        model = kwargs.get("model", None)
+        if model is not None:
+            self._flush_model(model)
+        if data is not None:
+            self._flush_data(data)
+        if model is None and data is None:
+            self.clear()
+
+    def _flush_model(self, model: Union[str, Type[DjangoModel]]) -> None:
+        """
+        Flush the cache for the given model.
+        """
+        if isinstance(model, str):
+            model = next((m for m in self.keys() if m.__name__ == model), None)
+        if model and model in self:
+            del self[model]
+
+    def _flush_data(self, data: Union[DjangoModel, Iterable[DjangoModel]]) -> None:
+        """
+        Flush the cache for the given data.
+        """
+        if isinstance(data, DjangoModel):
+            model = data.__class__
+            if model in self and data.pk in self[model]:
+                del self[model][data.pk]
+        else:
+            for instance in data:
+                model = instance.__class__
+                if model in self and instance.pk in self[model]:
+                    del self[model][instance.pk]
+
+    def set(self, data: Union[DjangoModel, Iterable[DjangoModel]]) -> None:
+        """
+        Set the cache for the given data.
+        """
+        if isinstance(data, DjangoModel):
+            self[data.__class__].update({data.pk: data})
+        else:
+            for instance in data:
+                self[instance.__class__].update({instance.pk: instance})
+
+
+class ThreadSafeCache(Cache):
+    """
+    A singleton cache object that allows sharing cache data between fields and instances.
+    This encapsulates the cache data inside a thread-safe singleton object.
+    Every model instance invoking a cache operation will use the same cache object,
+    allowing the cache data to be shared between them.
+    All mutation methods are protected by a threading lock for thread safety.
+    Connects to Django signals for cross-request cache invalidation.
+    """
+
+    _instance = None
+    _lock = threading.RLock()
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if not cls._instance:
+                    cls._instance = super().__new__(cls)
+
+        return cls._instance
+
+    def __init__(self) -> None:
+        if not hasattr(self, '_initialized'):
+            super().__init__()
+            self._initialized = True
+            post_save.connect(self._on_instance_save)
+            pre_delete.connect(self._on_instance_delete)
+
+    @staticmethod
+    def _on_instance_save(
+        sender: Type[DjangoModel], instance: DjangoModel, **kwargs
+    ) -> None:
+        """
+        Signal handler for saving a model instance.
+        """
+        cache = get_global_cache()
+        if cache and instance.__class__ in cache:
+            cache.set(instance)
+
+    @staticmethod
+    def _on_instance_delete(
+        sender: Type[DjangoModel], instance: DjangoModel, **kwargs
+    ) -> None:
+        """
+        Signal handler for deleting a model instance.
+        """
+        cache = get_global_cache()
+        if cache and instance.__class__ in cache:
+            cache.flush(instance)
+
+    def set(self, data: Union[DjangoModel, Iterable[DjangoModel]]) -> None:
+        with self._lock:
+            super().set(data)
+
+    def flush(
+        self, data: Union[DjangoModel, Iterable[DjangoModel], None] = None, **kwargs
+    ) -> None:
+        with self._lock:
+            super().flush(data, **kwargs)
+
+    def __setitem__(self, key, value):
+        with self._lock:
+            super().__setitem__(key, value)
+
+    def __delitem__(self, key):
+        with self._lock:
+            super().__delitem__(key)
+
+    def clear(self):
+        with self._lock:
+            super().clear()
+
+
+class ValueWithCache:
+    """
+    A class that represents a cached value.
+    This is used to retrieve values from the cache during the serialization process.
+    The retrieve method fetches the needed values and returns accordingly to the field type (ForeignKey, QuerySet, etc.).
+    """
+
+    def __init__(
+        self,
+        cache: Cache,
+        model: Type[DjangoModel],
+        value: Union[Iterable[Union[str, int]], str, int],
+    ) -> None:
+        self.cache: Cache = cache
+        self.value: Union[Iterable[Union[str, int]], str, int] = value
+        self.model: Type[DjangoModel] = model
+
+    def retrieve(self) -> Union[DjangoModel, DjangoQuerySet]:
+        """
+        Retrieve the value from the cache or database.
+        """
+        cache = self.cache.get(self.model)
+        if hasattr(self.value, "__iter__") and not isinstance(self.value, str):
+            pks = list(self.value)
+            if cache:
+                cached = [cache[i] for i in pks if i in cache]
+                missing_pks = [i for i in pks if i not in cache]
+                if missing_pks:
+                    fetched = list(self.model._default_manager.filter(pk__in=missing_pks))
+                    cached.extend(fetched)
+                    # Update cache with newly fetched instances
+                    for obj in fetched:
+                        cache[obj.pk] = obj
+                result = cached
+            else:
+                result = list(self.model._default_manager.filter(pk__in=pks))
+            # Preserve original PK ordering
+            pk_to_obj = {obj.pk: obj for obj in result}
+            ordered = [pk_to_obj[pk] for pk in pks if pk in pk_to_obj]
+            qs = self.model._default_manager.filter(pk__in=pks)
+            setattr(qs, "_result_cache", ordered)
+            return qs
+        else:
+            if cache:
+                val = cache.get(self.value, None)
+            else:
+                val = None
+            if val is None:
+                return self.model._default_manager.filter(pk=self.value).first()
+            else:
+                return val