Add Extractors utility class and ... (#45)

* Add Extractors utility class
Improve test coverage - all modules >= 90%

Author: rlubke

Makefile

@@ -118,8 +118,9 @@ generate-proto:  ## Generate Proto Files
 # ----------------------------------------------------------------------------------------------------------------------
 .PHONY: test
 test:  ##
-	pytest -W error --cov src/coherence --capture=tee-sys --cov-report=term --cov-report=html \
+	pytest -W error --cov src/coherence --cov-report=term --cov-report=html \
 		tests/test_serialization.py \
+		tests/test_extractors.py \
 		tests/test_session.py \
 		tests/test_client.py \
 		tests/test_events.py \

sonar-project.properties

@@ -0,0 +1 @@
+sonar.python.version=3.11

src/coherence/__init__.py

@@ -16,6 +16,7 @@
 from .client import Options as Options
 from .client import Session as Session
 from .client import TlsOptions as TlsOptions
+from .extractor import Extractors as Extractors
 from .filter import Filters as Filters
 from .processor import Processors as Processors
 

src/coherence/aggregator.py

@@ -10,7 +10,7 @@
 from typing import Any, Dict, Generic, List, Optional, TypeAlias, TypeVar
 
 from .comparator import Comparator, InverseComparator, SafeComparator
-from .extractor import ExtractorExpression, IdentityExtractor, ValueExtractor, extract
+from .extractor import ExtractorExpression, Extractors, ValueExtractor
 from .filter import Filter
 from .serialization import proxy
 
@@ -45,7 +45,7 @@ def __init__(self, extractor_or_property: Optional[ExtractorExpression[T, E]] =
             if isinstance(extractor_or_property, ValueExtractor):
                 self.extractor = extractor_or_property
             else:
-                self.extractor = extract(extractor_or_property)
+                self.extractor = Extractors.extract(extractor_or_property)
 
     def and_then(self, aggregator: EntryAggregator[R]) -> EntryAggregator[List[R]]:
         """
@@ -241,7 +241,7 @@ def __init__(
         self,
         number: int = 0,
         inverse: bool = False,
-        extractor: ValueExtractor[Any, Any] = IdentityExtractor(),
+        extractor: ValueExtractor[Any, Any] = Extractors.identity(),
         comparator: Optional[Comparator] = None,
         property_name: Optional[str] = None,
     ):
@@ -304,8 +304,7 @@ def extract(self, property_name: str) -> TopAggregator[E, R]:
         :param property_name: the property name
         :return:
         """
-        self.inverse = True  # TODO why is this True?
-        self.extractor = ValueExtractor.extract(property_name)
+        self.extractor = Extractors.extract(property_name)
         return self
 
 

src/coherence/extractor.py

@@ -263,13 +263,63 @@ def __init__(self, method: str) -> None:
         self.name = method
 
 
-def extract(expression: str) -> ValueExtractor[T, E]:
-    if "." in expression:
-        return ChainedExtractor(expression)
-    elif "," in expression:
-        return MultiExtractor(expression)
-    else:
-        return UniversalExtractor(expression)
+class Extractors:
+    """
+    A Utility class for creating extractors.
+    """
+
+    @classmethod
+    def extract(cls, expression: str, params: Optional[list[Any]] = None) -> ValueExtractor[T, E]:
+        """
+        If providing only an expression, the following rules apply:
+          - if the expression contains multiple values separated by a period,
+            the expression will be treated as a chained expression.  E.g.,
+            the expression 'a.b.c' would be treated as extract the 'a'
+            property, from that result, extract the 'b' property, and finally
+            from that result, extract the 'c' property.
+          - if the expression contains multiple values separated by a comma,
+            the expression will be treated as a multi expression.  E.g.,
+            the expression 'a,b,c' would be treated as extract the 'a', 'b',
+            and 'c' properties from the same object.
+          - for either case, the params argument is ignored.
+
+        It is also possible to invoke, and pass arguments to, arbitrary methods.
+        For example, if the target object of the extraction is a String, it's
+        possible to call the length() function by passing an expression of
+        "length()".  If the target method accepts arguments, provide a list
+        of one or more arguments to be passed.
+
+        :param expression: the extractor expression
+        :param params:  the params to pass to the method invocation
+        :return: a ValueExtractor based on the provided inputs
+        """
+        if expression is None:
+            raise ValueError("An expression must be provided")
+
+        if params is None or len(params) == 0:
+            if "." in expression:
+                return ChainedExtractor(expression)
+            elif "," in expression:
+                return MultiExtractor(expression)
+            else:
+                return UniversalExtractor(expression)
+
+        expr: str = expression
+        if not expr.endswith("()"):
+            expr = expr + "()"
+
+        return UniversalExtractor(expr, params)
+
+    @classmethod
+    def identity(cls) -> IdentityExtractor[Any]:
+        """
+        Returns an extractor that does not actually extract anything
+        from the passed value, but returns the value itself.
+
+        :return: an extractor that does not actually extract anything
+          from the passed value, but returns the value itself
+        """
+        return IdentityExtractor()
 
 
 ExtractorExpression: TypeAlias = ValueExtractor[T, E] | str

src/coherence/filter.py

@@ -7,7 +7,7 @@
 from abc import ABC
 from typing import Any, Generic, Set, TypeVar
 
-from .extractor import ExtractorExpression, ValueExtractor, extract
+from .extractor import ExtractorExpression, Extractors, ValueExtractor
 from .serialization import proxy
 
 E = TypeVar("E")
@@ -80,7 +80,7 @@ def __init__(self, extractor: ExtractorExpression[T, E]):
         if isinstance(extractor, ValueExtractor):
             self.extractor = extractor
         elif type(extractor) == str:
-            self.extractor = extract(extractor)
+            self.extractor = Extractors.extract(extractor)
         else:
             raise ValueError("extractor cannot be any other type")
 

src/coherence/processor.py

@@ -11,15 +11,14 @@
 from .extractor import (
     CompositeUpdater,
     ExtractorExpression,
-    IdentityExtractor,
+    Extractors,
     ManipulatorExpression,
     UniversalExtractor,
     UniversalUpdater,
     UpdaterExpression,
     ValueExtractor,
     ValueManipulator,
     ValueUpdater,
-    extract,
 )
 from .filter import Filter
 from .serialization import mappings, proxy
@@ -91,12 +90,12 @@ def __init__(self, value_extractor: ExtractorExpression[V, R]):
         """
         super().__init__()
         if value_extractor is None:
-            self.extractor: ValueExtractor[V, R] = IdentityExtractor()
+            self.extractor: ValueExtractor[V, R] = Extractors.identity()
         else:
             if isinstance(value_extractor, ValueExtractor):
                 self.extractor = value_extractor
             elif type(value_extractor) == str:
-                self.extractor = extract(value_extractor)
+                self.extractor = Extractors.extract(value_extractor)
             else:
                 raise ValueError("value_extractor cannot be any other type")
 
@@ -615,7 +614,7 @@ def extract(extractor: Optional[ExtractorExpression[T, E]] = None) -> EntryProce
                           processor or the name of the method to invoke via java reflection.  If `None`, an
                           :class:`coherence.extractor.IdentityExtractor` will be used.
         """
-        ext: ExtractorExpression[T, E] = extractor if extractor is not None else IdentityExtractor()
+        ext: ExtractorExpression[T, E] = extractor if extractor is not None else Extractors.identity()
         return ExtractorProcessor(ext)
 
     @staticmethod

tests/test_events.py

@@ -308,6 +308,22 @@ async def setup_and_teardown() -> AsyncGenerator[NamedCache[Any, Any], None]:
 # ----- test functions ------------------------------------------------------
 
 
+@pytest.mark.asyncio
+async def test_add_no_listener(setup_and_teardown: NamedCache[str, str]) -> None:
+    cache: NamedCache[str, str] = setup_and_teardown
+
+    with pytest.raises(ValueError):
+        await cache.add_map_listener(None)
+
+
+@pytest.mark.asyncio
+async def test_remove_no_listener(setup_and_teardown: NamedCache[str, str]) -> None:
+    cache: NamedCache[str, str] = setup_and_teardown
+
+    with pytest.raises(ValueError):
+        await cache.remove_map_listener(None)
+
+
 # noinspection PyShadowingNames
 @pytest.mark.asyncio
 async def test_all(setup_and_teardown: NamedCache[str, str]) -> None:

tests/test_extractors.py

@@ -0,0 +1,106 @@
+# Copyright (c) 2023, Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# https://oss.oracle.com/licenses/upl.
+
+from typing import Any, Optional, cast
+
+import pytest
+
+from coherence import Extractors
+from coherence.extractor import (
+    AbstractCompositeExtractor,
+    ChainedExtractor,
+    MultiExtractor,
+    UniversalExtractor,
+    ValueExtractor,
+)
+
+
+def test_extract_simple() -> None:
+    result = Extractors.extract("simple")
+    _validate_universal(result, "simple")
+
+
+def test_extract_chained() -> None:
+    result = Extractors.extract("prop1.prop2.prop3")
+    _validate_composite(result, ChainedExtractor, 3)
+
+    _validate_universal(result.extractors[0], "prop1")
+    _validate_universal(result.extractors[1], "prop2")
+    _validate_universal(result.extractors[2], "prop3")
+
+
+def test_extract_multi() -> None:
+    result = Extractors.extract("prop1,prop2,prop3")
+    _validate_composite(result, MultiExtractor, 3)
+
+    _validate_universal(result.extractors[0], "prop1")
+    _validate_universal(result.extractors[1], "prop2")
+    _validate_universal(result.extractors[2], "prop3")
+
+
+def test_extract_method_no_parens() -> None:
+    args = ["arg1", 10]
+    result = Extractors.extract("length", args)
+    _validate_universal(result, "length()", args)
+
+
+def test_extract_method_with_parens() -> None:
+    args = ["arg1", 10]
+    result = Extractors.extract("length()", args)
+    _validate_universal(result, "length()", args)
+
+
+def test_extract_no_expression() -> None:
+    with pytest.raises(ValueError):
+        Extractors.extract(None)
+
+
+def test_compose() -> None:
+    result = Extractors.extract("prop1")
+    result = result.compose(Extractors.extract("prop2"))
+
+    _validate_composite(result, ChainedExtractor, 2)
+
+    _validate_universal(result.extractors[0], "prop2")
+    _validate_universal(result.extractors[1], "prop1")
+
+
+def test_compose_no_extractor_arg() -> None:
+    result = Extractors.extract("prop1")
+    with pytest.raises(ValueError):
+        result.compose(None)
+
+
+def test_and_then_no_extractor_arg() -> None:
+    result = Extractors.extract("prop1")
+    with pytest.raises(ValueError):
+        result.and_then(None)
+
+
+def test_and_then() -> None:
+    result = Extractors.extract("prop1")
+    result = result.and_then(Extractors.extract("prop2"))
+
+    _validate_composite(result, ChainedExtractor, 2)
+
+    _validate_universal(result.extractors[0], "prop1")
+    _validate_universal(result.extractors[1], "prop2")
+
+
+def _validate_universal(extractor: ValueExtractor[Any, Any], expr: str, params: Optional[list[Any]] = None) -> None:
+    assert extractor is not None
+    assert isinstance(extractor, UniversalExtractor)
+
+    extractor_local = cast(UniversalExtractor, extractor)
+    assert extractor_local.name == expr
+    assert extractor_local.params == params
+
+
+def _validate_composite(extractor: ValueExtractor[Any, Any], expected_type: type, length: int) -> None:
+    assert extractor is not None
+    assert isinstance(extractor, expected_type)
+
+    extractor_local = cast(AbstractCompositeExtractor, extractor)
+    assert extractor_local.extractors is not None
+    assert len(extractor_local.extractors) == length

tests/test_session.py

@@ -14,7 +14,7 @@
 import pytest
 
 import tests
-from coherence import NamedCache, Options, Session, TlsOptions
+from coherence import NamedCache, NamedMap, Options, Session, TlsOptions
 from coherence.event import MapLifecycleEvent, SessionLifecycleEvent
 from tests import CountingMapListener
 
@@ -62,6 +62,14 @@ def check_basics() -> None:
     assert session.is_ready()
     assert not session.closed
 
+    cache = await session.get_cache("cache")
+    assert cache is not None
+    assert isinstance(cache, NamedCache)
+
+    map_local = await session.get_map("map")
+    assert map_local is not None
+    assert isinstance(map_local, NamedMap)
+
     await session.close()
     await asyncio.sleep(0.1)
 
@@ -70,10 +78,19 @@ def check_basics() -> None:
     assert not session.is_ready()
     assert session.closed
 
-    with pytest.raises(Exception):
-        await session.get_cache("test")
+    with pytest.raises(RuntimeError):
+        await cache.size()
+
+    with pytest.raises(RuntimeError):
+        await map_local.size()
+
+    with pytest.raises(RuntimeError):
+        await session.get_cache("cache")
+
+    with pytest.raises(RuntimeError):
+        await session.get_map("map")
 
-    with pytest.raises(Exception):
+    with pytest.raises(RuntimeError):
         session.on(SessionLifecycleEvent.CLOSED, lambda: None)