Added documentation and tests for instance info after import

docs/advanced_usage.rst

@@ -392,6 +392,47 @@ For example, you can use the 'isbn' number instead of 'id' to uniquely identify
     field(s) select more than one row, then a ``MultipleObjectsReturned`` exception will be raised.  If no row is
     identified, then ``DoesNotExist`` exception will be raised.
 
+Access instances after import
+=============================
+
+Access instance summary data
+----------------------------
+
+The instance pk and representation (i.e. output from ``repr()``) can be accessed after import::
+
+    rows = [
+        (1, 'Lord of the Rings'),
+    ]
+    dataset = tablib.Dataset(*rows, headers=['id', 'name'])
+    resource = BookResource()
+    result = resource.import_data(dataset)
+
+    for row_result in result:
+        print("%d: %s" % (row_result.object_id, row_result.object_repr))
+
+Access full instance data
+-------------------------
+
+All 'new', 'updated' and 'deleted' instances can be accessed after import if the
+:attr:`~import_export.resources.ResourceOptions.store_instance` meta attribute is set.
+
+For example, this snippet shows how you can retrieve persisted row data from a result::
+
+    class BookResourceWithStoreInstance(resources.ModelResource):
+        class Meta:
+            model = Book
+            store_instance = True
+
+    rows = [
+        (1, 'Lord of the Rings'),
+    ]
+    dataset = tablib.Dataset(*rows, headers=['id', 'name'])
+    resource = BookResourceWithStoreInstance()
+    result = resource.import_data(dataset)
+
+    for row_result in result:
+        print(row_result.instance.pk)
+
 Handling duplicate data
 =======================
 

docs/changelog.rst

@@ -4,7 +4,8 @@ Changelog
 3.3.2 (unreleased)
 ------------------
 
-- Nothing changed yet.
+- Updated Spanish translations (#1639)
+- Added documentation and tests for retrieving instance information after import (#1643)
 
 
 3.3.1 (2023-09-14)

tests/core/tests/test_resources.py

@@ -680,6 +680,9 @@ def test_import_data_new_store_instance(self):
         self.assertEqual(result.rows[0].import_type, results.RowResult.IMPORT_TYPE_NEW)
         self.assertIsNotNone(result.rows[0].instance)
         self.assertIsNone(result.rows[0].original)
+        self.assertEqual(1, Book.objects.count())
+        book = Book.objects.first()
+        self.assertEqual(book.pk, result.rows[0].instance.pk)
 
     def test_import_data_update_store_instance(self):
         self.resource = BookResourceWithStoreInstance()
@@ -689,6 +692,9 @@ def test_import_data_update_store_instance(self):
         )
         self.assertIsNotNone(result.rows[0].instance)
         self.assertIsNotNone(result.rows[0].original)
+        self.assertEqual(1, Book.objects.count())
+        book = Book.objects.first()
+        self.assertEqual(book.pk, result.rows[0].instance.pk)
 
     @skipUnlessDBFeature("supports_transactions")
     @mock.patch("import_export.resources.connections")