feature: lens (#86)

Author: Sune Debel

docs/effectful_but_side_effect_free.md

@@ -5,7 +5,7 @@ In functional programming, programs are built by composing functions that have n
 - `pfun.effect` helps you work with side-effects in functional style.
 
 
-If you have some experience with functionl programming, you can probably skip ahead to the section on `pfun.effect.Effect`.
+If you have some experience with functional programming, you can probably skip ahead to the section on `pfun.effect.Effect`.
 ## Maybe
 The job of the `pfun.maybe.Maybe` type is to help you work with missing values, in much the same way that the built-in `None` type is used. One of the main disadvantages of the `None` type is that you end up with logic for dealing with missing values all over the place, using code like `if foo is not None`.
 

docs/immutable_objects_and_data.md

@@ -69,3 +69,81 @@ assert 'new_key' not in d and d2.get('new_key') == Just('new_value')
 
 It supports the same api as `dict` which the exception of `__setitem__` which will raise an exception, and uses
 `pfun.maybe.Maybe` to indicate the presence or absence of a key when using `get`.
+
+## Lens
+Working with deeply nested immutable data-structures can be tricky when you want to transform only one member of an object deep inside the nested structure, but want to keep other the remaining data-structure intact, for example in:
+
+```python
+d = {
+    'a': {
+        'b': {
+            'c': 'I want to change this...'
+        }
+    },
+    'd': 'but not this'
+}
+new_d = d.copy()
+new_d['a'] = d['a'].copy()
+new_d['a']['b'] = d['a']['b'].copy()
+new_d['a']['b']['c'] = 'Phew! That took a lot of work!'
+```
+A _lens_ is a setter function that takes as arguments a value to replace at some path/index
+in an object/data-structure, and an object to transform. `pfun.lens` allows you
+to easily construct these setter functions by specifying the path/index at
+which you want to perform a replacement using normal Python indexing and attribute
+access. You use the object returned by `lens()` as a proxy for the object you want
+to transform by accessing attributes and indexes on it. The lens will remember this
+path, and use it when performing an update. You perform an update by calling the lens
+with the value to use as a replacement, and an object on which to perform the replacement:
+```python
+from pfun import lens
+
+
+t = lens()['a']['b']['c']
+new_d = t('Wow that was a lot easier!')(d)
+assert new_d['a']['b']['c'] == 'Wow that was a lot easier!'
+```
+If you use the `pfun` MyPy plugin, you can give a type as an argument to `lens`, which allows MyPy to check that the operations you make on the lens object are supported by the type you intend to transform:
+```python
+class Person:
+    name: str
+
+
+class User(Person):
+    organization: Organization
+
+
+u = lens(User)
+
+# MyPy type error because we misspelled 'organization'
+u.organisation('Foo Inc')
+
+# MyPy type error because "User.organization" must a "str"
+u.organization(0)
+
+# MyPy type error because "Person" is not a "User"
+u.organization('Foo Inc')(Person())
+```
+Since lenses are just Python callables, you can combine them using the normal
+compose operations available in `pfun`:
+```python
+from pfun import compose
+
+
+class NamedUser(User):
+    name: str
+
+
+u = lens(NamedUser)
+set_name = u.name
+set_org_name = u.organization.name
+
+new_user = compose(set_name('Bob'), set_org_name('Foo Inc'))(NamedUser())
+```
+Currently, `lens` supports working with the following types of objects and data-structures:
+
+- Regular Python objects
+- `collections.namedtuple` and `typing.NamedTuple` instances
+- normal and frozen `dataclasses.dataclass` and `pfun.Immutable`
+- `pfun.List`, `tuple` and `list`
+- `pfun.Dict` and `dict`

docs/lens_api.md

@@ -0,0 +1,12 @@
+::: pfun.lens.lens
+::: pfun.lens.RootLens
+    selection:
+        members: [
+            '__getattr__',
+            '__getitem__'
+        ]
+::: pfun.lens.Lens
+    selection:
+        members: [
+            '__call__'
+        ]

docs/useful_functions.md

@@ -1,5 +1,6 @@
 ## curry
-`curry` makes it easy to [curry](https://en.wikipedia.org/wiki/Currying) functions while inferring the resulting type signature with MyPy (if the `pfun` MyPy plugin is enabled).
+`curry` makes it easy to [curry](https://en.wikipedia.org/wiki/Currying) functions. If you enable the MyPy plugin, MyPy can also
+type check the arguments and return types of curried functions.
 
 The functions returned by `curry` support both normal and curried call styles:
 
@@ -26,55 +27,60 @@ def f(a, b='b', c='c'):
 
 assert f('a', c='c', b='b') == f(b='b')(a='a') == f(c='c')(a='a')(b='b') == ...
 ```
+To keep things simple, the actual signature of curried functions is simply the original function signature,
+which allows you to pass curried functions as arguments to functions that expects callbacks:
 
-To keep things simple, the `pfun` MyPy plugin doesn't infer all possible overloads of curried signatures. Instead, the inferred signature is split into the following argument lists: One argument list for optional arguments and `**kwargs` followed by one argument list for each positional argument. If the uncurried function accepts `*args`, it's added to the last positional argument list of the curried function
-
-In other words, given the following function `f`:
 ```python
+from typing import Callable
+
+from pfun import curry
+
 @curry
-def f(pos_1: T, pos_2: T, *args: T, keyword: T = '', **kwargs: T) -> T:
-    ...
-```
-the MyPy plugin infers the following overloaded signatures:
+def f(a: int, b: int) -> int: ...
 
-- **Curried signature without optional arguments**  
-`(pos_1: T) -> (pos_2: T, *args: T) -> T`
-- **Curried signature with optional arguments**  
-`(*, keyword: T =, **kwargs: T) -> (pos_1: T) -> (pos_2: T, *args: T) -> T`
-- **Uncurried signature**  
-`(pos_1: T, pos_2: T, *args: T, *, keyword: T =, **kwargs: T) -> T`
 
-The reasoning behind this behaviour is that the main use-case for currying is
-to pass partially applied functions as arguments to other functions that expect
-unary function arguments such as `pfun.effect.Effect.map` or `pfun.effect.Effect.and_then`,
-and in by-far most cases, we need the required arguments to be applied last:
+def h(g: Callable[[int], int]) - int: ...
+
+h(f(1))  # type safe
+```
+
+Because the signature of curried functions is not actually curried, this call will
+currently issue a false type error:
 
 ```python
-import operator as op
-from pfun.functions import curry
-from pfun.effect import success
+@curry
+def f(a: int, b: int) -> int: ...
 
-success(2).map(curry(op.add)(2)).run(None)
-4
+
+def h(g: Callable[[int], Callable[[int], int]]) -> int: ...
+
+
+h(f)  # false type error
 ```
 
-If this is not the behaviour you need, you can cast the result of calling a curried function,
-or use a `lambda`:
+If you need to take curried functions as callback arguments, this is a type-safe
+alternative
 ```python
-from typing import cast, Callable
-
+from pfun.functions import Curry, curry
 
 @curry
-def only_optional_args(a: str = 'a', b: str = 'b') -> str:
-    ...
+def f(a: int, b: int) -> int: ...
 
-# we need to cast here because the MyPy plugin does not infer this signature
-f = cast(Callable[[str], str], only_optional_args('c'))
+def h(g: Curry[Callable[[int, int], int]]) -> int: ...
 
-# alternatively, use a lambda
-f = lambda b: only_optional_args('c', b)
+
+h(f)  # type safe
 ```
+Currently the `curry` MyPy plugin doesn't support methods. If you want to return a curried function from a method you can use the following workaround:
+
+```python
+from pfun.functions import Curry, curry
 
+
+class C:
+    def f(self, x: int) -> Curry[[Callable[[int], int]]]:
+        return curry(lambda y: x + y)
+```
 ## compose
 
 `compose` makes it easy to compose functions while inferring the resulting type signature with MyPy (if the `pfun` MyPy plugin is enabled).

mkdocs.yml

@@ -8,10 +8,10 @@ nav:
     - 'Guide':
         - What Is This?: what_is_this.md
         - Install: install.md
-        - Effectful (But Side-Effect Free) Programming: effectful_but_side_effect_free.md
+        - Immutable Objects And Data Structures: immutable_objects_and_data.md
         - Useful Functions: useful_functions.md
+        - Effectful (But Side-Effect Free) Programming: effectful_but_side_effect_free.md
         - Curried And Type-Safe Operators: curried_and_typesafe_operators.md
-        - Immutable Objects And Data Structures: immutable_objects_and_data.md
         - Stack-Safety And Recursion: stack_safety.md
         - Property-Based Testing: property_based_testing.md
     - Other Resources: other_resources.md
@@ -33,6 +33,7 @@ nav:
         - 'pfun.trampoline': trampoline_api.md
         - 'pfun.hypothesis_strategies': hypothesis_strategies_api.md
         - 'pfun.operator': operator_api.md
+        - 'pfun.lens': lens_api.md
 theme:
     name: material
     palette:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pfun"
-version = "0.12.2"
+version = "0.12.3"
 description = ""
 authors = ["Sune Debel <sad@archii.ai>"]
 readme = "README.md"

src/pfun/__init__.py

@@ -4,6 +4,7 @@
 from .either import Either, Left, Right  # noqa
 from .functions import *  # noqa
 from .immutable import Immutable  # noqa
+from .lens import *  # noqa
 from .list import List  # noqa
 from .maybe import Just, Maybe, Nothing  # noqa
 

src/pfun/functions.py

@@ -154,7 +154,7 @@ def __init__(self, f: Callable):
         self._f = f  # type: ignore
 
     def __repr__(self):
-        return repr(self._f)
+        return f'curry({repr(self._f)})'
 
     def __call__(self, *args, **kwargs):
         signature = inspect.signature(self._f)
@@ -200,6 +200,23 @@ def decorator(*args, **kwargs):
     return decorator
 
 
+def flip(f: Callable) -> Callable:
+    """
+    Reverse the order of positional arguments of `f`
+
+    Example:
+        >>> f = lambda a, b, c: (a, b, c)
+        >>> flip(f)('a', 'b', 'c')
+        ('c', 'b', 'a')
+
+    Args:
+        f: Function to flip positional arguments of
+    Returns:
+        Function with positional arguments flipped
+    """
+    return curry(lambda *args, **kwargs: f(*reversed(args), **kwargs))
+
+
 __all__ = [
     'curry', 'always', 'compose', 'pipeline', 'identity', 'Unary', 'Predicate'
 ]

src/pfun/immutable.py

@@ -29,28 +29,5 @@ def __init_subclass__(
             frozen=True, init=init, repr=repr, eq=eq, order=order
         )(cls)
 
-    def clone(self: T, **kwargs) -> T:
-        """
-        Make a shallow copy of an instance, potentially overwriting
-        fields given by ``kwargs``
-
-        Example:
-            >>> class A(Immutable):
-            ...     a: str
-            >>> a = A('a')
-            >>> a2 = a.clone(a='new value')
-            >>> a2.a
-            "new value"
-
-        Args:
-            kwargs: fields to overwrite
-        Return:
-            New instance of same type with copied and overwritten fields
-
-        """
-        attrs = self.__dict__.copy()
-        attrs.update(kwargs)
-        return type(self)(**attrs)  # type: ignore
-
 
 __all__ = ['Immutable']