From a09eced267ea7923c20a7cc31ee9a874757daa45 Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@wuttaproject.org>
Date: Sat, 15 Feb 2025 23:06:31 -0600
Subject: [PATCH] Add LilSnippets-AddBatchSupportForImporter

---
 LilSnippets-AddBatchSupportForImporter.-.md | 43 +++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 LilSnippets-AddBatchSupportForImporter.-.md

diff --git a/LilSnippets-AddBatchSupportForImporter.-.md b/LilSnippets-AddBatchSupportForImporter.-.md
new file mode 100644
index 0000000..e537cdd
--- /dev/null
+++ b/LilSnippets-AddBatchSupportForImporter.-.md
@@ -0,0 +1,43 @@
+# Add Batch Support for Importer
+
+This assumes you already have a working importer, and wish to add "dynamic batch" support to it.
+
+As usual, the word "import" is used generically; in some cases "export" might make more sense.
+
+Here are the specifics behind the example shown in these instructions:
+
+ * import command is: `rattail import-sample`
+ * import handler is at: `rattail.importing.sample:FromSampleToRattail`
+ * importer is identified by `'Product'` and is at: `rattail.importing.sample:ProductImporter`
+ * importer does not yet support dynamic batches
+
+## Declare Batch Support
+
+The first step is simple enough.  You just need to declare support within the importer's class.  (This is the 3rd bullet from above.)
+
+In our example we would edit the `ProductImporter` class within `~/src/rattail/rattail/importing/sample.py`:
+
+```python
+class ProductImporter(FromSample, importing.model.ProductImporter):
+
+    # must add this
+    batches_supported = True
+```
+
+## Make Things Pretty
+
+Each row within an import batch will have an "object description" which is displayed in the Tailbone UI for instance.  By default this description is basically `str(obj)` where `obj` is the source "object" being imported.  Many times that default object description is not very helpful or pretty, in which case you can override.  To do so you must add the `'_object_str'` field to the normalized data returned by your importer (3rd bullet from above).
+
+In our example we would edit the `normalize_host_object()` method of the `ProductImporter` class within `~/src/rattail/rattail/importing/sample.py`:
+
+```python
+class ProductImporter(FromSample, importing.model.ProductImporter):
+
+    def normalize_host_object(self, csvrow):
+        data = super(ProductImporter, self).normalize_host_object(csvrow)
+
+        # must add this
+        data['_object_str'] = "custom description for object: {}".format(csvrow)
+
+        return data
+```