atdata 0.2.0a1__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,17 +199,8 @@ 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 )
 
 
@@ -217,13 +219,15 @@ 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 )