From 0f9eca5722941803d148b3cfd232f1ea1104733a Mon Sep 17 00:00:00 2001
From: purarue <7804791+purarue@users.noreply.github.com>
Date: Fri, 22 Nov 2024 15:58:29 -0800
Subject: [PATCH] doc: some performance notes for query_range

---
 my/core/__main__.py    | 3 +++
 my/core/query_range.py | 4 +++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/my/core/__main__.py b/my/core/__main__.py
index 00ac4ee..8da0ed4 100644
--- a/my/core/__main__.py
+++ b/my/core/__main__.py
@@ -538,6 +538,9 @@ def query_hpi_functions(
     # chain list of functions from user, in the order they wrote them on the CLI
     input_src = chain(*(f() for f in _locate_functions_or_prompt(qualified_names)))
 
+    # NOTE: if passing just one function to this which returns a single namedtuple/dataclass,
+    # using --order-key will often be faster as it does not need to duplicate the iterator in memory,
+    # or try to find the --order-value type on each object before sorting
     res = select_range(
         input_src,
         order_key=order_key,
diff --git a/my/core/query_range.py b/my/core/query_range.py
index 2a8d7bd..a2d6764 100644
--- a/my/core/query_range.py
+++ b/my/core/query_range.py
@@ -337,6 +337,8 @@ def select_range(
     # if the user supplied a order_key, and/or we've generated an order_value, create
     # the function that accesses that type on each value in the iterator
     if order_key is not None or order_value is not None:
+        # _generate_order_valeu_func internally here creates a copy of the iterator, which has to
+        # be consumed in-case we're sorting by mixed types
         order_by_chosen, itr = _handle_generate_order_by(itr, order_key=order_key, order_value=order_value)
         # signifies that itr is empty -- can early return here
         if order_by_chosen is None:
@@ -398,7 +400,7 @@ Specify a type or a key to order the value by""")
     return itr
 
 
-# re-use items from query for testing
+# reuse items from query for testing
 from .query import _A, _B, _Float, _mixed_iter_errors