Changes for COH-27559, COH-27560, COH-27561 (#2)

Improve generics; Flesh out utility classes.

Author: rlubke

.github/workflows/validate.yml

@@ -16,8 +16,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10"]
-        poetry-version: ["1.1.15"]
+        python-version: ["3.10.x", "3.11.x"]
+        poetry-version: ["1.4.2"]
         os: [ubuntu-latest]
     runs-on: ${{ matrix.os }}
     steps:

.gitignore

@@ -8,6 +8,7 @@
 .pytest_cache
 *.iml
 etc
+docs
 build
 poetry.lock
 __pycache__

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
         - id: black
 
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.1.1
+    rev: v1.2.0
     hooks:
         - id: mypy
 

coherence/__init__.py

@@ -2,8 +2,13 @@
 # Licensed under the Universal Permissive License v 1.0 as shown at
 # https://oss.oracle.com/licenses/upl.
 
+from __future__ import annotations
+
 __version__ = "0.1.0"
 
+from decimal import Decimal
+from typing import TypeAlias
+
 # expose these symbols in top-level namespace
 from .aggregator import Aggregators as Aggregators
 from .client import MapEntry as MapEntry
@@ -13,3 +18,4 @@
 from .client import Session as Session
 from .client import TlsOptions as TlsOptions
 from .filter import Filters as Filters
+from .processor import Processors as Processors

coherence/aggregator.py

@@ -388,7 +388,7 @@ def invoke_all(
 
     @abc.abstractmethod
     async def aggregate(
-        self, aggregator: EntryAggregator, keys: Optional[set[K]] = None, filter: Optional[Filter] = None
+        self, aggregator: EntryAggregator[R], keys: Optional[set[K]] = None, filter: Optional[Filter] = None
     ) -> R:
         """
         Perform an aggregating operation against the entries specified by the passed keys.
@@ -430,7 +430,7 @@ def entries(
     ) -> AsyncIterator[MapEntry[K, V]]:
         """
         Return a set view of the entries contained in this map that satisfy the criteria expressed by the filter.
-        Each element in the returned set is a :func:`coherence.client.MapEntry`.
+        Each element in the returned set is a :class:`coherence.client.MapEntry`.
 
         :param filter: the Filter object representing the criteria that the entries of this map should satisfy
         :param comparator: the Comparator object which imposes an ordering on entries in the resulting set; or `None`
@@ -643,7 +643,7 @@ def invoke_all(
 
     @_pre_call_cache
     async def aggregate(
-        self, aggregator: EntryAggregator, keys: Optional[set[K]] = None, filter: Optional[Filter] = None
+        self, aggregator: EntryAggregator[R], keys: Optional[set[K]] = None, filter: Optional[Filter] = None
     ) -> R:
         r = self._request_factory.aggregate_request(aggregator, keys, filter)
         results = await self._client_stub.aggregate(r)
@@ -926,16 +926,16 @@ class Session:
 
     This class emits the following events:
 
-        1. :func:`coherence.event.MapLifecycleEvent.DESTROYED`: when the underlying cache is destroyed
-        2. :func:`coherence.event.MapLifecycleEvent.TRUNCATED`: When the underlying cache is truncated
-        3. :func:`coherence.event.MapLifecycleEvent.RELEASED`: When the underlying cache is released
-        4. :func:`coherence.event.SessionLifecycleEvent.CONNECT`: when the Session detects the underlying `gRPC`
+        1. :class:`coherence.event.MapLifecycleEvent.DESTROYED`: when the underlying cache is destroyed
+        2. :class:`coherence.event.MapLifecycleEvent.TRUNCATED`: When the underlying cache is truncated
+        3. :class:`coherence.event.MapLifecycleEvent.RELEASED`: When the underlying cache is released
+        4. :class:`coherence.event.SessionLifecycleEvent.CONNECT`: when the Session detects the underlying `gRPC`
             channel has connected.
-        5. :func:`coherence.event.SessionLifecycleEvent.DISCONNECT`: when the Session detects the underlying `gRPC`
+        5. :class:`coherence.event.SessionLifecycleEvent.DISCONNECT`: when the Session detects the underlying `gRPC`
             channel has disconnected
-        6. :func:`coherence.event.SessionLifecycleEvent.RECONNECTED`: when the Session detects the underlying `gRPC`
+        6. :class:`coherence.event.SessionLifecycleEvent.RECONNECTED`: when the Session detects the underlying `gRPC`
             channel has re-connected
-        7. :func:`coherence.event.SessionLifecycleEvent.CLOSED`: when the Session has been closed
+        7. :class:`coherence.event.SessionLifecycleEvent.CLOSED`: when the Session has been closed
 
     """
 
@@ -1297,6 +1297,7 @@ async def __load_next_page(self) -> None:
 
         :return: None
         """
+        print("### DEBUG: __load_next_page() called!")
         request: PageRequest = self._client._request_factory.page_request(self._cookie)
         print("### DEBUG: __load_next_page() called!")
         self._stream = self._get_stream(request)

coherence/client.py

@@ -1,10 +1,11 @@
-# Copyright (c) 2022 Oracle and/or its affiliates.
+# Copyright (c) 2022, 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 __future__ import annotations
 
 from abc import ABC
+from typing import Any
 
 from coherence.extractor import UniversalExtractor
 from coherence.serialization import proxy
@@ -33,4 +34,4 @@ def __init__(self, property_name: str) -> None:
 class ExtractorComparator(Comparator):
     def __init__(self, property_name: str) -> None:
         super().__init__()
-        self.extractor = UniversalExtractor(property_name)
+        self.extractor = UniversalExtractor[Any](property_name)

coherence/comparator.py

@@ -1,20 +1,22 @@
-# Copyright (c) 2022 Oracle and/or its affiliates.
+# Copyright (c) 2022, 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 __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Optional, Sequence, TypeVar, cast
+from typing import Any, Generic, Optional, Sequence, TypeAlias, TypeVar, cast
 
 from coherence.serialization import proxy
 
-K = TypeVar("K", covariant=True)
-V = TypeVar("V", covariant=True)
-R = TypeVar("R", covariant=True)
+E = TypeVar("E")
+K = TypeVar("K")
+V = TypeVar("V")
+R = TypeVar("R")
+T = TypeVar("T")
 
 
-class ValueExtractor(ABC):
+class ValueExtractor(ABC, Generic[T, E]):
     def __init__(self) -> None:
         """
         ValueExtractor is used to both extract values (for example, for sorting or filtering) from an object,
@@ -24,7 +26,7 @@ def __init__(self) -> None:
         """
         super().__init__()
 
-    def compose(self, before: ValueExtractor) -> ValueExtractor:
+    def compose(self, before: ValueExtractor[T, E]) -> ValueExtractor[T, E]:
         """
         Returns a composed extractor that first applies the *before* extractor to its input, and then applies this
         extractor to the result. If evaluation of either extractor throws an exception, it is relayed to the caller
@@ -40,7 +42,7 @@ def compose(self, before: ValueExtractor) -> ValueExtractor:
         else:
             return ChainedExtractor([before, self])
 
-    def and_then(self, after: ValueExtractor) -> ValueExtractor:
+    def and_then(self, after: ValueExtractor[T, E]) -> ValueExtractor[T, E]:
         """
         Returns a composed extractor that first applies this extractor to its input, and then applies the *after*
         extractor to the result. If evaluation of either extractor throws an exception, it is relayed to the caller
@@ -57,19 +59,19 @@ def and_then(self, after: ValueExtractor) -> ValueExtractor:
             return after.compose(self)
 
     @classmethod
-    def extract(cls, from_field_or_method: str, params: Optional[list[Any]] = None) -> ValueExtractor:
+    def extract(cls, from_field_or_method: str, params: Optional[list[Any]] = None) -> ValueExtractor[T, E]:
         """
         Returns an extractor that extracts the value of the specified field.
 
-        :param from_field_or_method: he name of the field or method to extract the value from.
+        :param from_field_or_method: the name of the field or method to extract the value from.
         :param params: the parameters to pass to the method.
-        :return: an instance of :func:`coherence.extractor.UniversalExtractor`
+        :return: an instance of :class:`coherence.extractor.UniversalExtractor`
         """
         return UniversalExtractor(from_field_or_method, params)
 
 
 @proxy("extractor.UniversalExtractor")
-class UniversalExtractor(ValueExtractor):
+class UniversalExtractor(ValueExtractor[T, Any]):
     def __init__(self, name: str, params: Optional[list[Any]] = None) -> None:
         """
         Universal ValueExtractor implementation.
@@ -85,29 +87,29 @@ def __init__(self, name: str, params: Optional[list[Any]] = None) -> None:
         this extractor is considered a method extractor.
 
         :param name: A method or property name.
-        :param params: he parameter array. Must be `null` or `zero length` for a property based extractor.
+        :param params: the parameter array. Must be `null` or `zero length` for a property based extractor.
         """
         super().__init__()
         self.name: str = name
         self.params = params
 
     @classmethod
-    def create(cls, name: str, params: Optional[list[Any]] = None) -> UniversalExtractor:
+    def create(cls, name: str, params: Optional[list[Any]] = None) -> UniversalExtractor[T]:
         """
-        Class method to create an instance of :func:`coherence.extractor.UniversalExtractor`
+        Class method to create an instance of :class:`coherence.extractor.UniversalExtractor`
 
         :param name: A method or property name.
-        :param params: he parameter array. Must be `null` or `zero length` for a property based extractor.
-        :return: an instance of :func:`coherence.extractor.UniversalExtractor`
+        :param params: the parameter array. Must be `null` or `zero length` for a property based extractor.
+        :return: an instance of :class:`coherence.extractor.UniversalExtractor`
         """
         return cls(name, params)
 
 
-class AbstractCompositeExtractor(ValueExtractor):
-    def __init__(self, extractors: Sequence[ValueExtractor]) -> None:
+class AbstractCompositeExtractor(ValueExtractor[T, E]):
+    def __init__(self, extractors: Sequence[ValueExtractor[T, E]]) -> None:
         """
-        Abstract super class for :func:`coherence.extractor.ValueExtractor` implementations that are based on an
-        underlying array of :func:`coherence.extractor.ValueExtractor` objects.
+        Abstract super class for :class:`coherence.extractor.ValueExtractor` implementations that are based on an
+        underlying array of :class:`coherence.extractor.ValueExtractor` objects.
 
         :param extractors: an array of extractors
         """
@@ -116,35 +118,58 @@ def __init__(self, extractors: Sequence[ValueExtractor]) -> None:
 
 
 @proxy("extractor.ChainedExtractor")
-class ChainedExtractor(AbstractCompositeExtractor):
-    def __init__(self, extractors_or_method: str | Sequence[ValueExtractor]) -> None:
+class ChainedExtractor(AbstractCompositeExtractor[T, Any]):
+    def __init__(self, extractors_or_method: str | Sequence[ValueExtractor[T, Any]]) -> None:
         """
-        Composite :func:`coherence.extractor.ValueExtractor` implementation based on an array of extractors. The
+        Composite :class:`coherence.extractor.ValueExtractor` implementation based on an array of extractors. The
         extractors in the array are applied sequentially left-to-right, so a result of a previous extractor serves as
         a target object for a next one.
 
-        :param extractors_or_method: an array of :func:`coherence.extractor.ValueExtractor`, or a dot-delimited
+        :param extractors_or_method: an array of :class:`coherence.extractor.ValueExtractor`, or a dot-delimited
          sequence of method names which results in a ChainedExtractor that is based on an array of corresponding
-         :func:`coherence.extractor.UniversalExtractor` objects
+         :class:`coherence.extractor.UniversalExtractor` objects
         """
         if type(extractors_or_method) == str:
             e = list()
             names = extractors_or_method.split(".")
             for name in names:
-                v = UniversalExtractor(name)
+                v: UniversalExtractor[T] = UniversalExtractor(name)
                 e.append(v)
             super().__init__(e)
         else:
-            super().__init__(cast(Sequence[ValueExtractor], extractors_or_method))
+            super().__init__(cast(Sequence[ValueExtractor[T, Any]], extractors_or_method))
+
+
+@proxy("extractor.MultiExtractor")
+class MultiExtractor(AbstractCompositeExtractor[Any, Any]):
+    def __init__(self, extractors_or_method: str | Sequence[ValueExtractor[Any, Any]]) -> None:
+        """
+        Composite :class:`coherence.extractor.ValueExtractor` implementation based on an array of extractors. The
+        extractors in the array are applied sequentially left-to-right, so a result of a previous extractor serves as
+        a target object for a next one.
+
+        :param extractors_or_method: an array of :class:`coherence.extractor.ValueExtractor`, or a dot-delimited
+         sequence of method names which results in a ChainedExtractor that is based on an array of corresponding
+         :class:`coherence.extractor.UniversalExtractor` objects
+        """
+        if type(extractors_or_method) == str:
+            e = list()
+            names = extractors_or_method.split(",")
+            for name in names:
+                v: UniversalExtractor[Any] = UniversalExtractor(name)
+                e.append(v)
+            super().__init__(e)
+        else:
+            super().__init__(cast(Sequence[ValueExtractor[Any, Any]], extractors_or_method))
 
 
 @proxy("extractor.IdentityExtractor")
-class IdentityExtractor(ValueExtractor):
+class IdentityExtractor(ValueExtractor[T, Any]):
     __instance = None
 
     def __init__(self) -> None:
         """
-        A Trivial :func:`coherence.extractor.ValueExtractor` implementation that does not actually extract anything
+        A Trivial :class:`coherence.extractor.ValueExtractor` implementation that does not actually extract anything
         from the passed value, but returns the value itself.
 
         Constructs a new `IdentityExtractor` instance.
@@ -163,11 +188,11 @@ def __init__(self) -> None:
 
 
 class ValueManipulator(ValueUpdater):
-    """ValueManipulator represents a composition of :func:`coherence.extractor.ValueExtractor` and
-    :func:`coherence.extractor.ValueUpdater` implementations."""
+    """ValueManipulator represents a composition of :class:`coherence.extractor.ValueExtractor` and
+    :class:`coherence.extractor.ValueUpdater` implementations."""
 
     @abstractmethod
-    def get_extractor(self) -> ValueExtractor:
+    def get_extractor(self) -> ValueExtractor[T, E]:
         """
         Retrieve the underlying ValueExtractor reference.
 
@@ -188,7 +213,7 @@ class CompositeUpdater(ValueManipulator):
     """A ValueUpdater implementation based on an extractor-updater pair that could also be used as a
     ValueManipulator."""
 
-    def __init__(self, method_or_extractor: str | ValueExtractor, updater: Optional[ValueUpdater] = None) -> None:
+    def __init__(self, method_or_extractor: ExtractorExpression[T, E], updater: Optional[ValueUpdater] = None) -> None:
         """
         Constructs a new `CompositeUpdater`.
 
@@ -197,7 +222,7 @@ def __init__(self, method_or_extractor: str | ValueExtractor, updater: Optional[
         """
         super().__init__()
         if updater is not None:  # Two arg constructor
-            self.extractor = cast(ValueExtractor, method_or_extractor)
+            self.extractor = cast(ValueExtractor[T, E], method_or_extractor)
             self.updater = updater
         else:  # One arg with method name
             last = str(method_or_extractor).rfind(".")
@@ -207,7 +232,7 @@ def __init__(self, method_or_extractor: str | ValueExtractor, updater: Optional[
                 self.extractor = ChainedExtractor(str(method_or_extractor)[0:last])
             self.updater = UniversalUpdater(str(method_or_extractor)[last + 1 :])
 
-    def get_extractor(self) -> ValueExtractor:
+    def get_extractor(self) -> ValueExtractor[T, E]:
         return self.extractor
 
     def get_updator(self) -> ValueUpdater:
@@ -227,10 +252,24 @@ def __init__(self, method: str) -> None:
 
         If method ends in a '()', then the name is a method name. This implementation assumes that a target's class
         will have one and only one method with the specified name and this method will have exactly one parameter; if
-        the method is a property name, there should be a corresponding JavaBean property modifier method or it will
+        the method is a property name, there should be a corresponding JavaBean property modifier method, or it will
         be used as a key in a Map.
 
         :param method: a method or property name
         """
         super().__init__()
         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)
+
+
+ExtractorExpression: TypeAlias = ValueExtractor[T, E] | str
+ManipulatorExpression: TypeAlias = ValueManipulator | str
+UpdaterExpression: TypeAlias = ValueUpdater | str