Repository: django-import-export/django-import-export

Issue:
Is there any conflict between skip_diff and skip_unchanged?
skip_unchanged requires a comparison between the imported and persisted rows, skip_diff purports to skip that comparison.  Does that yield any conflict, or are they perfectly OK to use together?

If so, perhaps it makes sense to adjust the documentation to make this more clear.

Separately, skip_unchanged isn't called out anywhere as a potential performance optimization, but it seems like it would be one, if indeed it skips saving objects which it will not have not changed?


Discussion:

Resolving patch:
diff --git a/import_export/resources.py b/import_export/resources.py
--- a/import_export/resources.py
+++ b/import_export/resources.py
@@ -110,20 +110,38 @@ class ResourceOptions:
 
     skip_unchanged = False
     """
-    Controls if the import should skip unchanged records. Default value is
-    False
+    Controls if the import should skip unchanged records.
+    If ``True``, then each existing instance is compared with the instance to be
+    imported, and if there are no changes detected, the row is recorded as skipped,
+    and no database update takes place.
+
+    The advantages of enabling this option are:
+
+    #. Avoids unnecessary database operations which can result in performance
+       improvements for large datasets.
+
+    #. Skipped records are recorded in each :class:`~import_export.results.RowResult`.
+
+    #. Skipped records are clearly visible in the
+       :ref:`import confirmation page<import-process>`.
+
+    For the default ``skip_unchanged`` logic to work, the
+    :attr:`~import_export.resources.ResourceOptions.skip_diff` must also be ``False``
+    (which is the default):
+
+    Default value is ``False``.
     """
 
     report_skipped = True
     """
-    Controls if the result reports skipped rows. Default value is True
+    Controls if the result reports skipped rows. Default value is ``True``.
     """
 
     clean_model_instances = False
     """
     Controls whether ``instance.full_clean()`` is called during the import
     process to identify potential validation errors for each (non skipped) row.
-    The default value is False.
+    The default value is ``False``.
     """
 
     chunk_size = None
@@ -135,16 +153,22 @@ class ResourceOptions:
     skip_diff = False
     """
     Controls whether or not an instance should be diffed following import.
+
     By default, an instance is copied prior to insert, update or delete.
     After each row is processed, the instance's copy is diffed against the original,
     and the value stored in each :class:`~import_export.results.RowResult`.
     If diffing is not required, then disabling the diff operation by setting this value
     to ``True`` improves performance, because the copy and comparison operations are
     skipped for each row.
-    If enabled, then ``skip_row()`` checks do not execute, because 'skip' logic requires
-    comparison between the stored and imported versions of a row.
-    If enabled, then HTML row reports are also not generated (see ``skip_html_diff``).
-    The default value is False.
+
+    If enabled, then :meth:`~import_export.resources.Resource.skip_row` checks do not
+    execute, because 'skip' logic requires comparison between the stored and imported
+    versions of a row.
+
+    If enabled, then HTML row reports are also not generated, meaning that the
+    :attr:`~import_export.resources.ResourceOptions.skip_html_diff` value is ignored.
+
+    The default value is ``False``.
     """
 
     skip_html_diff = False
@@ -153,13 +177,16 @@ class ResourceOptions:
     By default, the difference between a stored copy and an imported instance
     is generated in HTML form and stored in each
     :class:`~import_export.results.RowResult`.
-    The HTML report is used to present changes on the confirmation screen in the admin
-    site, hence when this value is ``True``, then changes will not be presented on the
-    confirmation screen.
+
+    The HTML report is used to present changes in the
+    :ref:`import confirmation page<import-process>` in the admin site, hence when this
+    value is ``True``, then changes will not be presented on the confirmation screen.
+
     If the HTML report is not required, then setting this value to ``True`` improves
     performance, because the HTML generation is skipped for each row.
     This is a useful optimization when importing large datasets.
-    The default value is False.
+
+    The default value is ``False``.
     """
 
     use_bulk = False
@@ -175,13 +202,13 @@ class ResourceOptions:
     The default is to create objects in batches of 1000.
     See `bulk_create()
     <https://docs.djangoproject.com/en/dev/ref/models/querysets/#bulk-create>`_.
-    This parameter is only used if ``use_bulk`` is True.
+    This parameter is only used if ``use_bulk`` is ``True``.
     """
 
     force_init_instance = False
     """
-    If True, this parameter will prevent imports from checking the database for existing
-    instances.
+    If ``True``, this parameter will prevent imports from checking the database for
+    existing instances.
     Enabling this parameter is a performance enhancement if your import dataset is
     guaranteed to contain new instances.
     """
@@ -190,7 +217,7 @@ class ResourceOptions:
     """
     DB Connection name to use for db transactions. If not provided,
     ``router.db_for_write(model)`` will be evaluated and if it's missing,
-    DEFAULT_DB_ALIAS constant ("default") is used.
+    ``DEFAULT_DB_ALIAS`` constant ("default") is used.
     """
 
     store_row_values = False
@@ -211,10 +238,10 @@ class ResourceOptions:
 
     use_natural_foreign_keys = False
     """
-    If True, use_natural_foreign_keys = True will be passed to all foreign
+    If ``True``, this value will be passed to all foreign
     key widget fields whose models support natural foreign keys. That is,
     the model has a natural_key function and the manager has a
-    get_by_natural_key function.
+    ``get_by_natural_key()`` function.
     """
 
 


Test patch: