atdata 0.1.3b4__py3-none-any.whl → 0.2.2b1__py3-none-any.whl

atdata/lens.py

@@ -15,27 +15,29 @@ Lenses support the functional programming concept of composable, well-behaved
 transformations that satisfy lens laws (GetPut and PutGet).
 
 Example:
-    >>> @packable
-    ... class FullData:
-    ...     name: str
-    ...     age: int
-    ...     embedding: NDArray
-    ...
-    >>> @packable
-    ... class NameOnly:
-    ...     name: str
-    ...
-    >>> @lens
-    ... def name_view(full: FullData) -> NameOnly:
-    ...     return NameOnly(name=full.name)
-    ...
-    >>> @name_view.putter
-    ... def name_view_put(view: NameOnly, source: FullData) -> FullData:
-    ...     return FullData(name=view.name, age=source.age,
-    ...                     embedding=source.embedding)
-    ...
-    >>> ds = Dataset[FullData]("data.tar")
-    >>> ds_names = ds.as_type(NameOnly)  # Uses registered lens
+    ::
+
+        >>> @packable
+        ... class FullData:
+        ...     name: str
+        ...     age: int
+        ...     embedding: NDArray
+        ...
+        >>> @packable
+        ... class NameOnly:
+        ...     name: str
+        ...
+        >>> @lens
+        ... def name_view(full: FullData) -> NameOnly:
+        ...     return NameOnly(name=full.name)
+        ...
+        >>> @name_view.putter
+        ... def name_view_put(view: NameOnly, source: FullData) -> FullData:
+        ...     return FullData(name=view.name, age=source.age,
+        ...                     embedding=source.embedding)
+        ...
+        >>> ds = Dataset[FullData]("data.tar")
+        >>> ds_names = ds.as_type(NameOnly)  # Uses registered lens
 """
 
 ##
@@ -60,6 +62,8 @@ from typing import (
 if TYPE_CHECKING:
     from .dataset import PackableSample
 
+from ._protocols import Packable
+
 
 ##
 # Typing helpers
@@ -67,8 +71,8 @@ if TYPE_CHECKING:
 DatasetType: TypeAlias = Type['PackableSample']
 LensSignature: TypeAlias = Tuple[DatasetType, DatasetType]
 
-S = TypeVar( 'S', bound = 'PackableSample' )
-V = TypeVar( 'V', bound = 'PackableSample' )
+S = TypeVar( 'S', bound = Packable )
+V = TypeVar( 'V', bound = Packable )
 type LensGetter[S, V] = Callable[[S], V]
 type LensPutter[S, V] = Callable[[V, S], S]
 
@@ -84,19 +88,22 @@ class Lens( Generic[S, V] ):
     and an optional putter that transforms ``(V, S) -> S``, enabling updates to
     the view to be reflected back in the source.
 
-    Type Parameters:
+    Parameters:
         S: The source type, must derive from ``PackableSample``.
         V: The view type, must derive from ``PackableSample``.
 
     Example:
-        >>> @lens
-        ... def name_lens(full: FullData) -> NameOnly:
-        ...     return NameOnly(name=full.name)
-        ...
-        >>> @name_lens.putter
-        ... def name_lens_put(view: NameOnly, source: FullData) -> FullData:
-        ...     return FullData(name=view.name, age=source.age)
+        ::
+
+            >>> @lens
+            ... def name_lens(full: FullData) -> NameOnly:
+            ...     return NameOnly(name=full.name)
+            ...
+            >>> @name_lens.putter
+            ... def name_lens_put(view: NameOnly, source: FullData) -> FullData:
+            ...     return FullData(name=view.name, age=source.age)
     """
+    # TODO The above has a line for "Parameters:" that should be "Type Parameters:"; this is a temporary fix for `quartodoc` auto-generation bugs.
 
     def __init__( self, get: LensGetter[S, V],
                 put: Optional[LensPutter[S, V]] = None
@@ -113,8 +120,7 @@ class Lens( Generic[S, V] ):
                 trivial putter is used that ignores updates to the view.
 
         Raises:
-            AssertionError: If the getter function doesn't have exactly one
-                parameter.
+            ValueError: If the getter function doesn't have exactly one parameter.
         """
         ##
 
@@ -122,14 +128,17 @@ class Lens( Generic[S, V] ):
 
         sig = inspect.signature( get )
         input_types = list( sig.parameters.values() )
-        assert len( input_types ) == 1, \
-            'Wrong number of input args for lens: should only have one'
+        if len(input_types) != 1:
+            raise ValueError(
+                f"Lens getter must have exactly one parameter, got {len(input_types)}: "
+                f"{[p.name for p in input_types]}"
+            )
 
         # Update function details for this object as returned by annotation
         functools.update_wrapper( self, get )
 
-        self.source_type: Type[PackableSample] = input_types[0].annotation
-        self.view_type: Type[PackableSample] = sig.return_annotation
+        self.source_type: Type[Packable] = input_types[0].annotation
+        self.view_type: Type[Packable] = sig.return_annotation
 
         # Store the getter
         self._getter = get
@@ -155,9 +164,11 @@ class Lens( Generic[S, V] ):
             The putter function, allowing this to be used as a decorator.
 
         Example:
-            >>> @my_lens.putter
-            ... def my_lens_put(view: ViewType, source: SourceType) -> SourceType:
-            ...     return SourceType(...)
+            ::
+
+                >>> @my_lens.putter
+                ... def my_lens_put(view: ViewType, source: SourceType) -> SourceType:
+                ...     return SourceType(...)
         """
         ##
         self._putter = put
@@ -188,35 +199,10 @@ class Lens( Generic[S, V] ):
         """
         return self( s )
 
-    # Convenience to enable calling the lens as its getter
-
     def __call__( self, s: S ) -> V:
-        """Apply the lens transformation (same as ``get()``).
-
-        Args:
-            s: The source sample of type ``S``.
-
-        Returns:
-            A view of the source as type ``V``.
-        """
+        """Apply the lens transformation (same as ``get()``)."""
         return self._getter( s )
 
-# TODO Figure out how to properly parameterize this
-# def _lens_factory[S, V]( register: bool = True ):
-#     """Register the annotated function `f` as the getter of a sample lens"""
-
-#     # The actual lens decorator taking a lens getter function to a lens object
-#     def _decorator( f: LensGetter[S, V] ) -> Lens[S, V]:
-#         ret = Lens[S, V]( f )
-#         if register:
-#             _network.register( ret )
-#         return ret
-    
-#     # Return the lens decorator
-#     return _decorator
-
-# # For convenience
-# lens = _lens_factory
 
 def lens(  f: LensGetter[S, V] ) -> Lens[S, V]:
     """Decorator to create and register a lens transformation.
@@ -233,25 +219,21 @@ def lens(  f: LensGetter[S, V] ) -> Lens[S, V]:
         or decorated with ``@lens_name.putter`` to add a putter function.
 
     Example:
-        >>> @lens
-        ... def extract_name(full: FullData) -> NameOnly:
-        ...     return NameOnly(name=full.name)
-        ...
-        >>> @extract_name.putter
-        ... def extract_name_put(view: NameOnly, source: FullData) -> FullData:
-        ...     return FullData(name=view.name, age=source.age)
+        ::
+
+            >>> @lens
+            ... def extract_name(full: FullData) -> NameOnly:
+            ...     return NameOnly(name=full.name)
+            ...
+            >>> @extract_name.putter
+            ... def extract_name_put(view: NameOnly, source: FullData) -> FullData:
+            ...     return FullData(name=view.name, age=source.age)
     """
     ret = Lens[S, V]( f )
     _network.register( ret )
     return ret
 
 
-##
-# Global registry of used lenses
-
-# _registered_lenses: Dict[LensSignature, Lens] = dict()
-# """TODO"""
-
 class LensNetwork:
     """Global registry for lens transformations between sample types.
 
@@ -292,18 +274,6 @@ class LensNetwork:
             If a lens already exists for the same type pair, it will be
             overwritten.
         """
-
-        # sig = inspect.signature( _lens.get )
-        # input_types = list( sig.parameters.values() )
-        # assert len( input_types ) == 1, \
-        #     'Wrong number of input args for lens: should only have one'
-        
-        # input_type = input_types[0].annotation
-        # print( input_type )
-        # output_type = sig.return_annotation
-
-        # self._registry[input_type, output_type] = _lens
-        # print( _lens.source_type )
         self._registry[_lens.source_type, _lens.view_type] = _lens
     
     def transform( self, source: DatasetType, view: DatasetType ) -> Lens:
@@ -323,8 +293,6 @@ class LensNetwork:
             Currently only supports direct transformations. Compositional
             transformations (chaining multiple lenses) are not yet implemented.
         """
-
-        # TODO Handle compositional closure
         ret = self._registry.get( (source, view), None )
         if ret is None:
             raise ValueError( f'No registered lens from source {source} to view {view}' )
@@ -332,22 +300,5 @@ class LensNetwork:
         return ret
 
 
-# Create global singleton registry instance
-_network = LensNetwork()
-
-# def lens( f: LensPutter ) -> Lens:
-#     """Register the annotated function `f` as a sample lens"""
-#     ##
-    
-#     sig = inspect.signature( f )
-
-#     input_types = list( sig.parameters.values() )
-#     output_type = sig.return_annotation
-    
-#     _registered_lenses[]
-
-#     f.lens = Lens(
-
-#     )
-
-#     return f
+# Global singleton registry instance
+_network = LensNetwork()