Django documentation updates and swappable model improvements (#2422)

* Allow use of non-default database

* Allow custom models to be specified

* Allow swappable models

* Switch to in-memory db for django tests

* Test database parameter

* Improve introspection

* Update documentation

* Update documentation

Author: gunthercox

chatterbot/ext/django_chatterbot/abstract_models.py

@@ -3,25 +3,15 @@
 from django.db import models
 from django.utils import timezone
 from django.conf import settings
+from django.apps import apps
 
 
 DJANGO_APP_NAME = constants.DEFAULT_DJANGO_APP_NAME
-STATEMENT_MODEL = 'Statement'
-TAG_MODEL = 'Tag'
 
-if hasattr(settings, 'CHATTERBOT'):
-    """
-    Allow related models to be overridden in the project settings.
-    Default to the original settings if one is not defined.
-    """
-    DJANGO_APP_NAME = settings.CHATTERBOT.get(
-        'django_app_name',
-        DJANGO_APP_NAME
-    )
-    STATEMENT_MODEL = settings.CHATTERBOT.get(
-        'statement_model',
-        STATEMENT_MODEL
-    )
+# Default model paths for swappable models
+# These can be overridden via CHATTERBOT_STATEMENT_MODEL and CHATTERBOT_TAG_MODEL settings
+DEFAULT_STATEMENT_MODEL = f'{DJANGO_APP_NAME}.Statement'
+DEFAULT_TAG_MODEL = f'{DJANGO_APP_NAME}.Tag'
 
 
 class AbstractBaseTag(models.Model):
@@ -88,7 +78,9 @@ class AbstractBaseStatement(models.Model, StatementMixin):
     )
 
     tags = models.ManyToManyField(
-        TAG_MODEL,
+        settings.CHATTERBOT_TAG_MODEL if hasattr(
+            settings, 'CHATTERBOT_TAG_MODEL'
+        ) else DEFAULT_TAG_MODEL,
         related_name='statements',
         help_text='The tags that are associated with this statement.'
     )
@@ -117,17 +109,51 @@ def __str__(self):
             return self.text
         return '<empty>'
 
+    @classmethod
+    def get_tag_model(cls):
+        """
+        Return the Tag model class, respecting the swappable setting.
+
+        This method checks:
+        1. Django settings (CHATTERBOT_TAG_MODEL) - project-wide configuration
+        2. The model referenced by the 'tags' field - handles custom models via kwargs
+        3. Falls back to DEFAULT_TAG_MODEL if introspection fails
+
+        This ensures the correct Tag model is used even when custom models
+        are specified via storage adapter kwargs rather than Django settings.
+        """
+        tag_model_path = getattr(settings, 'CHATTERBOT_TAG_MODEL', None)
+
+        if tag_model_path:
+            return apps.get_model(tag_model_path)
+
+        # If no setting, infer from the ManyToManyField relationship for
+        # cases where custom models are specified via kwargs
+        try:
+            # Get the model that this class's 'tags' field points to
+            tags_field = cls._meta.get_field('tags')
+            related_model = tags_field.related_model
+
+            # Resolve strings (lazy references)
+            if isinstance(related_model, str):
+                return apps.get_model(related_model)
+            return related_model
+        except Exception:
+            # Fallback to default if introspection fails
+            return apps.get_model(DEFAULT_TAG_MODEL)
+
     def get_tags(self) -> list[str]:
         """
         Return the list of tags for this statement.
-        (Overrides the method from StatementMixin)
         """
         return list(self.tags.values_list('name', flat=True))
 
     def add_tags(self, *tags):
         """
         Add a list of strings to the statement as tags.
-        (Overrides the method from StatementMixin)
         """
-        for _tag in tags:
-            self.tags.get_or_create(name=_tag)
+        TagModel = self.get_tag_model()
+
+        for tag_name in tags:
+            tag_obj, _created = TagModel.objects.get_or_create(name=tag_name)
+            self.tags.add(tag_obj)

chatterbot/ext/django_chatterbot/models.py

@@ -5,12 +5,22 @@ class Statement(AbstractBaseStatement):
     """
     A statement represents a single spoken entity, sentence or
     phrase that someone can say.
+
+    This model can be swapped for a custom model by setting
+    CHATTERBOT_STATEMENT_MODEL in your Django settings.
     """
-    pass
+
+    class Meta:
+        swappable = 'CHATTERBOT_STATEMENT_MODEL'
 
 
 class Tag(AbstractBaseTag):
     """
     A label that categorizes a statement.
+
+    This model can be swapped for a custom model by setting
+    CHATTERBOT_TAG_MODEL in your Django settings.
     """
-    pass
+
+    class Meta:
+        swappable = 'CHATTERBOT_TAG_MODEL'

chatterbot/storage/django_storage.py

@@ -6,27 +6,56 @@ class DjangoStorageAdapter(StorageAdapter):
     """
     Storage adapter that allows ChatterBot to interact with
     Django storage backends.
+
+    :param database: The Django database alias to use (default: 'default')
+    :type database: str
+    :param statement_model: The Statement model to use (default: reads from CHATTERBOT_STATEMENT_MODEL setting)
+    :type statement_model: str
+    :param tag_model: The Tag model to use (default: reads from CHATTERBOT_TAG_MODEL setting)
+    :type tag_model: str
     """
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
+        from django.conf import settings
 
         self.django_app_name = kwargs.get(
             'django_app_name',
             constants.DEFAULT_DJANGO_APP_NAME
         )
 
+        self.database = kwargs.get('database', 'default')
+
+        # Support custom models via kwargs or Django settings
+        self.statement_model = kwargs.get(
+            'statement_model',
+            getattr(
+                settings,
+                'CHATTERBOT_STATEMENT_MODEL',
+                f'{self.django_app_name}.Statement'
+            )
+        )
+
+        self.tag_model = kwargs.get(
+            'tag_model',
+            getattr(
+                settings,
+                'CHATTERBOT_TAG_MODEL',
+                f'{self.django_app_name}.Tag'
+            )
+        )
+
     def get_statement_model(self):
         from django.apps import apps
-        return apps.get_model(self.django_app_name, 'Statement')
+        return apps.get_model(self.statement_model)
 
     def get_tag_model(self):
         from django.apps import apps
-        return apps.get_model(self.django_app_name, 'Tag')
+        return apps.get_model(self.tag_model)
 
     def count(self) -> int:
         Statement = self.get_model('statement')
-        return Statement.objects.count()
+        return Statement.objects.using(self.database).count()
 
     def filter(self, **kwargs):
         """
@@ -53,7 +82,7 @@ def filter(self, **kwargs):
         if tags:
             kwargs['tags__name__in'] = tags
 
-        statements = Statement.objects.filter(**kwargs)
+        statements = Statement.objects.using(self.database).filter(**kwargs)
 
         if exclude_text:
             statements = statements.exclude(
@@ -115,12 +144,12 @@ def create(self, **kwargs):
 
         statement = Statement(**kwargs)
 
-        statement.save()
+        statement.save(using=self.database)
 
         tags_to_add = []
 
         for _tag in tags:
-            tag, _ = Tag.objects.get_or_create(name=_tag)
+            tag, _ = Tag.objects.using(self.database).get_or_create(name=_tag)
             tags_to_add.append(tag)
 
         statement.tags.add(*tags_to_add)
@@ -143,15 +172,15 @@ def create_many(self, statements):
 
             statement_model_object = Statement(**statement_data)
 
-            statement_model_object.save()
+            statement_model_object.save(using=self.database)
 
             tags_to_add = []
 
             for tag_name in tag_data:
                 if tag_name in tag_cache:
                     tag = tag_cache[tag_name]
                 else:
-                    tag, _ = Tag.objects.get_or_create(name=tag_name)
+                    tag, _ = Tag.objects.using(self.database).get_or_create(name=tag_name)
                     tag_cache[tag_name] = tag
                 tags_to_add.append(tag)
 
@@ -165,9 +194,9 @@ def update(self, statement):
         Tag = self.get_model('tag')
 
         if hasattr(statement, 'id'):
-            statement.save()
+            statement.save(using=self.database)
         else:
-            statement = Statement.objects.create(
+            statement = Statement.objects.using(self.database).create(
                 text=statement.text,
                 search_text=statement.search_text,
                 conversation=statement.conversation,
@@ -177,7 +206,7 @@ def update(self, statement):
             )
 
         for _tag in statement.tags.all():
-            tag, _ = Tag.objects.get_or_create(name=_tag)
+            tag, _ = Tag.objects.using(self.database).get_or_create(name=_tag)
 
             statement.tags.add(tag)
 
@@ -189,7 +218,7 @@ def get_random(self):
         """
         Statement = self.get_model('statement')
 
-        statement = Statement.objects.order_by('?').first()
+        statement = Statement.objects.using(self.database).order_by('?').first()
 
         if statement is None:
             raise self.EmptyDatabaseException()
@@ -204,7 +233,7 @@ def remove(self, statement_text):
         """
         Statement = self.get_model('statement')
 
-        statements = Statement.objects.filter(text=statement_text)
+        statements = Statement.objects.using(self.database).filter(text=statement_text)
 
         statements.delete()
 
@@ -215,5 +244,5 @@ def drop(self):
         Statement = self.get_model('statement')
         Tag = self.get_model('tag')
 
-        Statement.objects.all().delete()
-        Tag.objects.all().delete()
+        Statement.objects.using(self.database).all().delete()
+        Tag.objects.using(self.database).all().delete()