Merged release-4

docs/changelog.rst

@@ -1,7 +1,9 @@
 Changelog
 =========
 
-Please refer to :doc:`release notes<release_notes>`.
+.. warning::
+
+    Version 4 introduces breaking changes.  Please refer to :doc:`release notes<release_notes>`.
 
 4.0.0-beta.3 (unreleased)
 -------------------------
@@ -10,6 +12,7 @@ Please refer to :doc:`release notes<release_notes>`.
 - Added customizable ``MediaStorage`` (#1708)
 - Relocated admin integration section from advanced_usage.rst into new file (#1713)
 - Fix slow export with ForeignKey id (#1717)
+- Added customization of Admin UI import error messages (#1727)
 - Improve output of error messages (#1729)
 
 4.0.0-beta.2 (2023-12-09)
@@ -20,7 +23,7 @@ Please refer to :doc:`release notes<release_notes>`.
 - Support export from model change form (#1687)
 - Updated Admin UI to track deleted and skipped Imports (#1691)
 - Import form defaults to read-only field if only one format defined (#1690)
-- Refactored :module:`~import_export.resources` into separate modules for ``declarative`` and ``options`` (#1695)
+- Refactored :mod:`~import_export.resources` into separate modules for ``declarative`` and ``options`` (#1695)
 - fix multiple inheritance not setting options (#1696)
 - Refactored tests to remove dependencies between tests (#1703)
 - Handle python3.12 datetime deprecations (#1705)

docs/release_notes.rst

@@ -70,6 +70,8 @@ Deprecations
 
 * Use of ``ExportViewFormMixin`` is deprecated.  See `this issue <https://github.com/django-import-export/django-import-export/issues/1666>`_.
 
+* See :ref:`renamed_methods`.
+
 Admin UI
 ========
 
@@ -136,6 +138,8 @@ method calls, and to allow easier extensibility.
 :class:`import_export.resources.Resource`
 -----------------------------------------
 
+.. _renamed_methods:
+
 Renamed methods
 ^^^^^^^^^^^^^^^
 
@@ -200,41 +204,41 @@ This section describes methods in which the parameters have changed.
 
    * - ``save_m2m(self, obj, data, using_transactions, dry_run)``
      - ``save_m2m(self, instance, row, **kwargs)``
-     - * ``dry_run`` param now in ``kwargs``
-       * ``using_transactions`` param now in ``kwargs``
-       * ``row`` added as mandatory arg
+     - * ``row`` added as mandatory arg
        * ``obj`` renamed to ``instance``
        * ``data`` renamed to ``row``
+       * ``dry_run`` param now in ``kwargs``
+       * ``using_transactions`` param now in ``kwargs``
 
    * - ``before_save_instance(self, instance, using_transactions, dry_run)``
      - ``before_save_instance(self, instance, row, **kwargs)``
-     - * ``dry_run`` param now in ``kwargs``
+     - * ``row`` added as mandatory arg
+       * ``dry_run`` param now in ``kwargs``
        * ``using_transactions`` param now in ``kwargs``
-       * ``row`` added as mandatory arg
 
    * - ``after_save_instance(self, instance, using_transactions, dry_run)``
      - ``after_save_instance(self, instance, row, **kwargs)``
-     - * ``dry_run`` param now in ``kwargs``
+     - * ``row`` added as mandatory arg
+       * ``dry_run`` param now in ``kwargs``
        * ``using_transactions`` param now in ``kwargs``
-       * ``row`` added as mandatory arg
 
    * - ``delete_instance(self, instance, using_transactions=True, dry_run=False)``
      - ``delete_instance(self, instance, row, **kwargs)``
-     - * ``dry_run`` param now in ``kwargs``
+     - * ``row`` added as mandatory arg
+       * ``dry_run`` param now in ``kwargs``
        * ``using_transactions`` param now in ``kwargs``
-       * ``row`` added as mandatory arg
 
    * - ``before_delete_instance(self, instance, dry_run)``
      - ``before_delete_instance(self, instance, row, **kwargs)``
-     - * ``dry_run`` param now in ``kwargs``
+     - * ``row`` added as mandatory arg
+       * ``dry_run`` param now in ``kwargs``
        * ``using_transactions`` param now in ``kwargs``
-       * ``row`` added as mandatory arg
 
    * - ``after_delete_instance(self, instance, dry_run)``
      - ``after_delete_instance(self, instance, row, **kwargs)``
-     - * ``dry_run`` param now in ``kwargs``
+     - * ``row`` added as mandatory arg
+       * ``dry_run`` param now in ``kwargs``
        * ``using_transactions`` param now in ``kwargs``
-       * ``row`` added as mandatory arg
 
    * - ``before_export(self, queryset, *args, **kwargs)``
      - ``before_export(self, queryset, **kwargs)``

import_export/resources.py

@@ -4,6 +4,7 @@
 from collections import OrderedDict
 from copy import deepcopy
 from html import escape
+from warnings import warn
 
 import tablib
 from diff_match_patch import diff_match_patch
@@ -422,6 +423,18 @@ def import_field(self, field, instance, row, is_m2m=False, **kwargs):
     def get_import_fields(self):
         return [self.fields[f] for f in self.get_import_order()]
 
+    def import_obj(self, obj, data, dry_run, **kwargs):
+        warn(
+            "The 'import_obj' method is deprecated and will be replaced "
+            "with 'import_instance(self, instance, row, **kwargs)' "
+            "in a future release.  Refer to Release Notes for details.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        if dry_run is True:
+            kwargs.update({"dry_run": dry_run})
+        self.import_instance(obj, data, **kwargs)
+
     def import_instance(self, instance, row, **kwargs):
         r"""
         Traverses every field in this Resource and calls
@@ -614,6 +627,18 @@ def after_import_row(self, row, row_result, **kwargs):
         """
         pass
 
+    def after_import_instance(self, instance, new, row_number=None, **kwargs):
+        warn(
+            "The 'after_import_instance' method is deprecated and will be replaced "
+            "with 'after_init_instance(self, instance, new, row, **kwargs)' "
+            "in a future release.  Refer to Release Notes for details.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        if row_number is not None:
+            kwargs.update({"row_number": row_number})
+        self.after_init_instance(instance, new, None, **kwargs)
+
     def after_init_instance(self, instance, new, row, **kwargs):
         r"""
         Override to add additional logic. Does nothing by default.

import_export/templates/admin/import_export/import.html

@@ -85,7 +85,6 @@ <h2>{% translate "Errors" %}</h2>
           <div class="traceback">{{ error.traceback|linebreaks }}</div>
         </li>
         {% endfor %}
-        {% block import_error_list %}
         {% for line, errors in result.row_errors %}
           {% for error in errors %}
             {% block import_error_list_item %}
@@ -100,10 +99,8 @@ <h2>{% translate "Errors" %}</h2>
               <div class="import-error-display-traceback">{{ error.traceback|linebreaks }}</div>
               {% endif %}
             </li>
-            {% endblock %}
           {% endfor %}
         {% endfor %}
-        {% endblock %}
       </ul>
     {% endblock %}
 

tests/core/tests/test_resources/test_resources.py

@@ -1,5 +1,6 @@
 import json
 import sys
+import warnings
 from collections import OrderedDict
 from datetime import date
 from decimal import Decimal, InvalidOperation
@@ -1890,3 +1891,59 @@ class Meta:
 
     def test_resource_gets_correct_model_from_string(self):
         self.assertEqual(self.resource._meta.model, Book)
+
+
+class DeprecatedMethodTest(TestCase):
+    """
+    These tests relate to renamed methods in v4.
+    The tests can be removed when the deprecated methods are removed.
+    """
+
+    def setUp(self):
+        rows = [
+            ["1", "Ulysses"],
+        ]
+        self.dataset = tablib.Dataset(*rows, headers=["id", "name"])
+        self.obj = Book.objects.create(id=1, name="Ulysses")
+
+    def test_import_obj_renamed(self):
+        resource = BookResource()
+        with self.assertWarns(
+            DeprecationWarning,
+        ):
+            resource.import_obj(self.obj, self.dataset, dry_run=True)
+
+    def test_import_obj_passes_params(self):
+        class MyBookResource(resources.ModelResource):
+            def import_instance(self, instance, row, **kwargs):
+                self.kwargs = kwargs
+
+            class Meta:
+                model = Book
+
+        resource = MyBookResource()
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            resource.import_obj(self.obj, self.dataset, True)
+        self.assertTrue(resource.kwargs["dry_run"])
+
+    def test_after_import_instance_renamed(self):
+        resource = BookResource()
+        with self.assertWarns(
+            DeprecationWarning,
+        ):
+            resource.after_import_instance(self.obj, True, row_number=1)
+
+    def test_after_import_instance_passes_params(self):
+        class MyBookResource(resources.ModelResource):
+            def after_init_instance(self, instance, new, row, **kwargs):
+                self.kwargs = kwargs
+
+            class Meta:
+                model = Book
+
+        resource = MyBookResource()
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            resource.after_import_instance(self.obj, True, row_number=1)
+        self.assertEqual(1, resource.kwargs["row_number"])