feat(querylist): get() first result (#435)

Author: tony

CHANGES

@@ -15,6 +15,13 @@ $ pip install --user --upgrade --pre libvcs
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
+### New
+
+- QueryList learned to `.get()` to pick the first result (#435)
+
+  - Raises error if no items found (unless `default=` keyword argument passed)
+  - Raises error if multipe items found
+
 ## libvcs 0.20.0 (2022-10-31)
 
 ### What's new

src/libvcs/_internal/query_list.py

@@ -11,6 +11,7 @@
 from typing import Any, Callable, Optional, Protocol, TypeVar, Union
 
 T = TypeVar("T", Any, Any)
+no_arg = object()
 
 
 def keygetter(
@@ -370,6 +371,9 @@ class QueryList(list[T]):
     >>> query.filter(foods__fruit__in="banana")[0].city
     'Tampa'
 
+    >>> query.get(foods__fruit__in="banana").city
+    'Tampa'
+
     **With objects (nested)**:
 
     >>> from typing import Optional
@@ -417,6 +421,9 @@ class QueryList(list[T]):
     >>> query.filter(food__fruit__in="banana")[0].city
     'Tampa'
 
+    >>> query.get(food__fruit__in="banana").city
+    'Tampa'
+
     >>> query.filter(food__breakfast="waffles")
     [Restaurant(place='Chicago suburbs',
         city='Elmhurst',
@@ -506,3 +513,18 @@ def val_match(obj: Union[str, list[Any]]) -> bool:
             _filter = filter_lookup
 
         return self.__class__(k for k in self if _filter(k))
+
+    def get(
+        self,
+        matcher: Optional[Union[Callable[[T], bool], T]] = None,
+        default: Optional[Any] = no_arg,
+        **kwargs: Any,
+    ) -> Optional[T]:
+        objs = self.filter(matcher=matcher, **kwargs)
+        if len(objs) > 1:
+            raise Exception("Multiple objects returned")
+        elif len(objs) == 0:
+            if default == no_arg:
+                raise Exception("No objects found")
+            return default
+        return objs[0]

tests/_internal/test_query_list.py

@@ -257,3 +257,28 @@ def test_filter(
             assert qs.filter(filter_expr) == expected_result
     else:
         assert qs.filter() == expected_result
+
+    if (
+        isinstance(expected_result, list)
+        and len(expected_result) > 0
+        and not isinstance(expected_result[0], dict)
+    ):
+        if len(expected_result) == 1:
+            if isinstance(filter_expr, dict):
+                assert qs.get(**filter_expr) == expected_result[0]
+            else:
+                assert qs.get(filter_expr) == expected_result[0]
+        elif len(expected_result) > 1:
+            with pytest.raises(Exception) as e:
+                if isinstance(filter_expr, dict):
+                    assert qs.get(**filter_expr) == expected_result
+                else:
+                    assert qs.get(filter_expr) == expected_result
+                assert e.match("Multiple objects returned")
+        elif len(expected_result) == 0:
+            with pytest.raises(Exception) as e:
+                if isinstance(filter_expr, dict):
+                    assert qs.get(**filter_expr) == expected_result
+                else:
+                    assert qs.get(filter_expr) == expected_result
+            assert e.match("No objects found")