From 268fc3a1c3b2adb94e33bffd6cd5f2fc0e8bcef1 Mon Sep 17 00:00:00 2001
From: Quirin Pamp <pamp@atix.de>
Date: Tue, 31 Oct 2023 16:01:05 +0100
Subject: [PATCH] Expose batch_qs to plugin API

closes #4607
---
 CHANGES/plugin_api/4607.feature |  1 +
 pulpcore/app/util.py            | 24 +++++++++++++++---------
 pulpcore/plugin/util.py         |  1 +
 3 files changed, 17 insertions(+), 9 deletions(-)
 create mode 100644 CHANGES/plugin_api/4607.feature

diff --git a/CHANGES/plugin_api/4607.feature b/CHANGES/plugin_api/4607.feature
new file mode 100644
index 0000000000..0e6bb58a5c
--- /dev/null
+++ b/CHANGES/plugin_api/4607.feature
@@ -0,0 +1 @@
+Exposed a function to return a batch from a given queryset at ``pulpcore.plugin.util.batch_qs``.
diff --git a/pulpcore/app/util.py b/pulpcore/app/util.py
index e0f429d502..eb479d2328 100644
--- a/pulpcore/app/util.py
+++ b/pulpcore/app/util.py
@@ -180,15 +180,21 @@ def get_view_name_for_model(model_obj, view_action):
 
 
 def batch_qs(qs, batch_size=1000):
-    """
-    Returns a queryset batch in the given queryset.
-
-    Usage:
-        # Make sure to order your querset
-        article_qs = Article.objects.order_by('id')
-        for qs in batch_qs(article_qs):
-            for article in qs:
-                print article.body
+    """Returns a queryset batch from the given queryset.
+
+    Make sure to order the queryset.
+
+    Args:
+       qs: The queryset we want to iterate over in batches.
+       batch_size: Defaults to 1000.
+
+    Example:
+        To iterate over a queryset while retrieving records from the DB in batches, use::
+
+            article_qs = Article.objects.order_by('id')
+            for qs in batch_qs(article_qs):
+                for article in qs:
+                    print article.body
     """
     total = qs.count()
     for start in range(0, total, batch_size):
diff --git a/pulpcore/plugin/util.py b/pulpcore/plugin/util.py
index 25cfa3c154..38bb21b6fb 100644
--- a/pulpcore/plugin/util.py
+++ b/pulpcore/plugin/util.py
@@ -13,6 +13,7 @@
 )
 
 from pulpcore.app.util import (  # noqa: F401
+    batch_qs,
     extract_pk,
     get_artifact_url,
     get_url,