Added m2m_field_name util functions

These should help with often having to check which values are returned
by `m2m_field_name()` and `m2m_reverse_field_name()` - since they're
both undocumented.
Also, if Django changes the mentioned internal methods, it'll be easier
to only update these two functions instead of all the places they
are / will be used.

Author: ddabble

simple_history/models.py

@@ -684,11 +684,8 @@ def create_historical_record_m2ms(self, history_instance, instance):
 
             insert_rows = []
 
-            # `m2m_field_name()` is part of Django's internal API
-            through_field_name = field.m2m_field_name()
-
+            through_field_name = utils.get_m2m_field_name(field)
             rows = through_model.objects.filter(**{through_field_name: instance})
-
             for row in rows:
                 insert_row = {"history": history_instance}
 

simple_history/tests/tests/test_utils.py

@@ -1,3 +1,4 @@
+import unittest
 from datetime import datetime
 from unittest import skipUnless
 from unittest.mock import Mock, patch
@@ -14,22 +15,88 @@
     Document,
     Place,
     Poll,
+    PollChildBookWithManyToMany,
+    PollChildRestaurantWithManyToMany,
     PollWithAlternativeManager,
     PollWithExcludeFields,
     PollWithHistoricalSessionAttr,
+    PollWithManyToMany,
+    PollWithManyToManyCustomHistoryID,
+    PollWithManyToManyWithIPAddress,
+    PollWithSelfManyToMany,
+    PollWithSeveralManyToMany,
     PollWithUniqueQuestion,
     Street,
 )
 from simple_history.utils import (
     bulk_create_with_history,
     bulk_update_with_history,
     get_history_manager_for_model,
+    get_history_model_for_model,
+    get_m2m_field_name,
+    get_m2m_reverse_field_name,
     update_change_reason,
 )
 
 User = get_user_model()
 
 
+class GetM2MFieldNamesTestCase(unittest.TestCase):
+    def test__get_m2m_field_name__returns_expected_value(self):
+        def field_names(model):
+            history_model = get_history_model_for_model(model)
+            # Sort the fields, to prevent flaky tests
+            fields = sorted(history_model._history_m2m_fields, key=lambda f: f.name)
+            return [get_m2m_field_name(field) for field in fields]
+
+        self.assertListEqual(field_names(PollWithManyToMany), ["pollwithmanytomany"])
+        self.assertListEqual(
+            field_names(PollWithManyToManyCustomHistoryID),
+            ["pollwithmanytomanycustomhistoryid"],
+        )
+        self.assertListEqual(
+            field_names(PollWithManyToManyWithIPAddress),
+            ["pollwithmanytomanywithipaddress"],
+        )
+        self.assertListEqual(
+            field_names(PollWithSeveralManyToMany), ["pollwithseveralmanytomany"] * 3
+        )
+        self.assertListEqual(
+            field_names(PollChildBookWithManyToMany),
+            ["pollchildbookwithmanytomany"] * 2,
+        )
+        self.assertListEqual(
+            field_names(PollChildRestaurantWithManyToMany),
+            ["pollchildrestaurantwithmanytomany"] * 2,
+        )
+        self.assertListEqual(
+            field_names(PollWithSelfManyToMany), ["from_pollwithselfmanytomany"]
+        )
+
+    def test__get_m2m_reverse_field_name__returns_expected_value(self):
+        def field_names(model):
+            history_model = get_history_model_for_model(model)
+            # Sort the fields, to prevent flaky tests
+            fields = sorted(history_model._history_m2m_fields, key=lambda f: f.name)
+            return [get_m2m_reverse_field_name(field) for field in fields]
+
+        self.assertListEqual(field_names(PollWithManyToMany), ["place"])
+        self.assertListEqual(field_names(PollWithManyToManyCustomHistoryID), ["place"])
+        self.assertListEqual(field_names(PollWithManyToManyWithIPAddress), ["place"])
+        self.assertListEqual(
+            field_names(PollWithSeveralManyToMany), ["book", "place", "restaurant"]
+        )
+        self.assertListEqual(
+            field_names(PollChildBookWithManyToMany), ["book", "place"]
+        )
+        self.assertListEqual(
+            field_names(PollChildRestaurantWithManyToMany), ["place", "restaurant"]
+        )
+        self.assertListEqual(
+            field_names(PollWithSelfManyToMany), ["to_pollwithselfmanytomany"]
+        )
+
+
 class BulkCreateWithHistoryTestCase(TestCase):
     def setUp(self):
         self.data = [

simple_history/utils.py

@@ -57,6 +57,30 @@ def get_app_model_primary_key_name(model):
     return model._meta.pk.name
 
 
+def get_m2m_field_name(m2m_field: ManyToManyField) -> str:
+    """
+    Returns the field name of an M2M field's through model that corresponds to the model
+    the M2M field is defined on.
+
+    E.g. for a ``votes`` M2M field on a ``Poll`` model that references a ``Vote`` model
+    (and with a default-generated through model), this function would return ``"poll"``.
+    """
+    # This method is part of Django's internal API
+    return m2m_field.m2m_field_name()
+
+
+def get_m2m_reverse_field_name(m2m_field: ManyToManyField) -> str:
+    """
+    Returns the field name of an M2M field's through model that corresponds to the model
+    the M2M field references.
+
+    E.g. for a ``votes`` M2M field on a ``Poll`` model that references a ``Vote`` model
+    (and with a default-generated through model), this function would return ``"vote"``.
+    """
+    # This method is part of Django's internal API
+    return m2m_field.m2m_reverse_field_name()
+
+
 def bulk_create_with_history(
     objs,
     model,