Rename mark_lazy -> passthrough_lazy_args

Technologicat · Technologicat · commit 5d7936d21a7c · 2019-12-15T01:00:21.000+02:00
Also improve its explanation in docstrings and comments.
diff --git a/unpythonic/env.py b/unpythonic/env.py
@@ -4,11 +4,11 @@
 __all__ = ["env"]
 
 from collections.abc import Container, Sized, Iterable, Mapping, MutableMapping
-from .lazyutil import mark_lazy
+from .lazyutil import passthrough_lazy_args
 
 # co-operate with unpythonic.syntax.lazify; this is essentially a binding construct,
 # so it shouldn't force any promises that are stuffed into the env.
-@mark_lazy
+@passthrough_lazy_args
 class env:
     """Environment for let-like constructs.
 
diff --git a/unpythonic/fun.py b/unpythonic/fun.py
@@ -25,8 +25,8 @@
 from .dynassign import dyn, make_dynvar
 from .regutil import register_decorator
 
-# we use @mark_lazy (and handle possible lazy args) to support unpythonic.syntax.lazify.
-from .lazyutil import mark_lazy, islazy, force, force1, maybe_force_args
+# we use @passthrough_lazy_args (and handle possible lazy args) to support unpythonic.syntax.lazify.
+from .lazyutil import passthrough_lazy_args, islazy, force, force1, maybe_force_args
 
 @register_decorator(priority=10)
 def memoize(f):
@@ -57,7 +57,7 @@ def memoized(*args, **kwargs):
             raise value
         return value
     if islazy(f):
-        memoized = mark_lazy(memoized)
+        memoized = passthrough_lazy_args(memoized)
     return memoized
 
 #def memoize_simple(f):  # essential idea, without exception handling
@@ -71,7 +71,7 @@ def memoized(*args, **kwargs):
 #    return memoized
 
 make_dynvar(curry_context=[])
-@mark_lazy
+@passthrough_lazy_args
 def _currycall(f, *args, **kwargs):
     """Co-operate with unpythonic.syntax.curry.
 
@@ -86,7 +86,7 @@ def _currycall(f, *args, **kwargs):
     return curry(f, *args, _curry_force_call=True, _curry_allow_uninspectable=True, **kwargs)
 
 @register_decorator(priority=90)
-@mark_lazy
+@passthrough_lazy_args
 def curry(f, *args, _curry_force_call=False, _curry_allow_uninspectable=False, **kwargs):
     """Decorator: curry the function f.
 
@@ -200,7 +200,7 @@ def curried(*args, **kwargs):
             if len(args) < min_arity:
                 p = partial(f, *args, **kwargs)
                 if islazy(f):
-                    p = mark_lazy(p)
+                    p = passthrough_lazy_args(p)
                 return curry(p)
             # passthrough on right, like https://github.com/Technologicat/spicy
             if len(args) > max_arity:
@@ -223,7 +223,7 @@ def curried(*args, **kwargs):
                 return (now_result,) + later_args
             return maybe_force_args(f, *args, **kwargs)
     if islazy(f):
-        curried = mark_lazy(curried)
+        curried = passthrough_lazy_args(curried)
     curried._is_curried_function = True  # stash for detection
     # curry itself is curried: if we get args, they're the first step
     if args or kwargs or _curry_force_call:
@@ -249,7 +249,7 @@ def flip(f):
     def flipped(*args, **kwargs):
         return maybe_force_args(f, *reversed(args), **kwargs)
     if islazy(f):
-        flipped = mark_lazy(flipped)
+        flipped = passthrough_lazy_args(flipped)
     return flipped
 
 def rotate(k):
@@ -279,11 +279,11 @@ def rotated(*args, **kwargs):
             rargs = args[-j:] + args[:-j]
             return maybe_force_args(f, *rargs, **kwargs)
         if islazy(f):
-            rotated = mark_lazy(rotated)
+            rotated = passthrough_lazy_args(rotated)
         return rotated
     return rotate_k
 
-@mark_lazy
+@passthrough_lazy_args
 def apply(f, arg0, *more, **kwargs):
     """Scheme/Racket-like apply.
 
@@ -366,7 +366,7 @@ def notf(f):  # Racket: negate
     def negated(*args, **kwargs):
         return not maybe_force_args(f, *args, **kwargs)
     if islazy(f):
-        negated = mark_lazy(negated)
+        negated = passthrough_lazy_args(negated)
     return negated
 
 def andf(*fs):  # Racket: conjoin
@@ -392,7 +392,7 @@ def conjoined(*args, **kwargs):
                 return False
         return b
     if all(islazy(f) for f in fs):
-        conjoined = mark_lazy(conjoined)
+        conjoined = passthrough_lazy_args(conjoined)
     return conjoined
 
 def orf(*fs):  # Racket: disjoin
@@ -420,7 +420,7 @@ def disjoined(*args, **kwargs):
                 return b
         return False
     if all(islazy(f) for f in fs):
-        disjoined = mark_lazy(disjoined)
+        disjoined = passthrough_lazy_args(disjoined)
     return disjoined
 
 def _make_compose1(direction):  # "left", "right"
@@ -443,7 +443,7 @@ def compose1(fs):
         #  - if fs contains only one item, we output it as-is
         composed = reducel(compose1_two, fs)  # op(elt, acc)
         if all(islazy(f) for f in fs):
-            composed = mark_lazy(composed)
+            composed = passthrough_lazy_args(composed)
         return composed
     return compose1
 
@@ -505,7 +505,7 @@ def composed(*args):
     def compose(fs):
         composed = reducel(compose_two, fs)  # op(elt, acc)
         if all(islazy(f) for f in fs):
-            composed = mark_lazy(composed)
+            composed = passthrough_lazy_args(composed)
         return composed
     return compose
 
@@ -591,7 +591,7 @@ def apply_f_to_kth_arg(*args):
             out.extend(args[m:])
         return tuple(out)
     if islazy(f):
-        apply_f_to_kth_arg = mark_lazy(apply_f_to_kth_arg)
+        apply_f_to_kth_arg = passthrough_lazy_args(apply_f_to_kth_arg)
     return apply_f_to_kth_arg
 
 def to1st(f):
@@ -663,5 +663,5 @@ def fwithself(*args, **kwargs):
         #return f(fwithself, *args, **kwargs)
         return maybe_force_args(f, fwithself, *args, **kwargs)  # support unpythonic.syntax.lazify
     if islazy(f):
-        fwithself = mark_lazy(fwithself)
+        fwithself = passthrough_lazy_args(fwithself)
     return fwithself
diff --git a/unpythonic/lazyutil.py b/unpythonic/lazyutil.py
@@ -5,7 +5,7 @@
 upon which other regular code is allowed to depend.
 """
 
-__all__ = ["mark_lazy", "maybe_force_args", "force1", "force"]
+__all__ = ["passthrough_lazy_args", "maybe_force_args", "force1", "force"]
 
 from .regutil import register_decorator
 from .dynassign import make_dynvar
@@ -31,19 +31,48 @@ class Lazy:
 # -----------------------------------------------------------------------------
 
 @register_decorator(priority=95)
-def mark_lazy(f):
-    """Internal. Helps calling lazy functions from outside a ``with lazify`` block."""
-    f._lazy = True
+def passthrough_lazy_args(f):
+    """Mark a function for passthrough of lazy args.
+
+    When a function has this mark, its arguments won't be forced by
+    ``maybe_force_args``. This is the only effect the mark has.
+
+    This is useful for decorating "infrastructure" functions that are strict
+    (i.e. not lazy; defined outside any `with lazify` block), but do not need
+    to access the values of all of their arguments. Usually the reason is that
+    those arguments are just passed through for actual access elsewhere.
+
+    If needed, it's still possible to force individual arguments inside the
+    body of a function decorated with this, using `force` or `force1`.
+
+    For example, `curry` uses this strategy to find out which function it
+    should call (by forcing only its argument `f`), but it does not need to
+    access the values of any of its other arguments. Those other arguments are
+    just passed on to the function in question, so that's the correct place to
+    make the lazy/strict distinction for those arguments. (`curry` then uses
+    `maybe_force_args` to make the actual call, so that the call target is
+    also checked for this mark.)
+
+    ***CAUTION***: The mark is implemented as an attribute on the function
+    object. Hence, if the result is wrapped by another decorator, the mark
+    won't be active on the final decorated function.
+
+    The exact position where you want this in the decorator list depends
+    on what exactly you're doing - the priority is set to `95` to make this
+    apply before `curry`, so that `curry` will see the mark.
+    """
+    f._passthrough_lazy_args = True
     return f
 
 def islazy(f):
-    """Internal. Return whether the function f is marked as lazy.
+    """Return whether the function f is marked for passthrough of lazy args.
 
-    When a function is marked as lazy, its arguments won't be forced by
-    ``maybe_force_args``. This is the only effect the mark has.
+    This is mainly used internally by `unpythonic.syntax.lazify`, but is
+    provided as part of the public API, so that also user code can inspect
+    the mark if it needs to.
     """
     # special-case "_let" for lazify/curry combo when let[] expressions are present
-    return hasattr(f, "_lazy") or (hasattr(f, "__name__") and f.__name__ == "_let")
+    return hasattr(f, "_passthrough_lazy_args") or (hasattr(f, "__name__") and f.__name__ == "_let")
 
 def maybe_force_args(f, *thunks, **kwthunks):
     """Internal. Helps calling strict functions from inside a ``with lazify`` block."""
diff --git a/unpythonic/misc.py b/unpythonic/misc.py
@@ -14,15 +14,15 @@
 from queue import Empty
 
 from .regutil import register_decorator
-from .lazyutil import mark_lazy, maybe_force_args, force
+from .lazyutil import passthrough_lazy_args, maybe_force_args, force
 
 # Only the single-argument form (just f) is supported by unpythonic.syntax.util.sort_lambda_decorators.
 #
 # This is as it should be; if given any arguments beside f, the call doesn't conform
 # to the decorator API, but is a normal function call. See "callwith" if you need to
 # pass arguments and then call f from a decorator position.
 @register_decorator(priority=80)
-@mark_lazy
+@passthrough_lazy_args
 def call(f, *args, **kwargs):
     """Call the function f.
 
@@ -93,7 +93,7 @@ def _():
     return maybe_force_args(force(f), *args, **kwargs)  # support unpythonic.syntax.lazify
 
 @register_decorator(priority=80)
-@mark_lazy
+@passthrough_lazy_args
 def callwith(*args, **kwargs):
     """Freeze arguments, choose function later.
 
diff --git a/unpythonic/syntax/autoref.py b/unpythonic/syntax/autoref.py
@@ -12,7 +12,7 @@
 from .letdoutil import isdo, islet, ExpandedDoView, ExpandedLetView
 
 from ..dynassign import dyn
-from ..lazyutil import force1, mark_lazy
+from ..lazyutil import force1, passthrough_lazy_args
 
 # with autoref(o):
 # with autoref(scipy.loadmat("mydata.mat")):       # evaluate once, assign to a gensym
@@ -69,7 +69,7 @@
 # to ``o`` and ``p`` directly), so that arbitrary expressions can be autoref'd without giving them
 # a name in user code.
 
-@mark_lazy
+@passthrough_lazy_args
 def _autoref_resolve(args):
     *objs, s = [force1(x) for x in args]
     for o in objs:
diff --git a/unpythonic/syntax/lazify.py b/unpythonic/syntax/lazify.py
@@ -15,7 +15,7 @@
 from .util import suggest_decorator_index, sort_lambda_decorators, detect_lambda, \
                   isx, make_isxpred, getname, is_decorator, wrapwith
 from .letdoutil import islet, isdo, ExpandedLetView
-from ..lazyutil import mark_lazy, force, force1, maybe_force_args
+from ..lazyutil import passthrough_lazy_args, force, force1, maybe_force_args
 from ..dynassign import dyn
 
 # -----------------------------------------------------------------------------
@@ -214,18 +214,18 @@ def f(tree):
                 # to allow also strict code to call this function
                 if type(tree) is Lambda:
                     lam = tree
-                    tree = hq[mark_lazy(ast_literal[tree])]
+                    tree = hq[passthrough_lazy_args(ast_literal[tree])]
                     tree = sort_lambda_decorators(tree)
                     lam.body = rec(lam.body)
                 else:
                     tree.decorator_list = rec(tree.decorator_list)
-                    k = suggest_decorator_index("mark_lazy", tree.decorator_list)
+                    k = suggest_decorator_index("passthrough_lazy_args", tree.decorator_list)
                     if k is not None:
-                        tree.decorator_list.insert(k, hq[mark_lazy])
+                        tree.decorator_list.insert(k, hq[passthrough_lazy_args])
                     else:
-                        # mark_lazy should generally be as innermost as possible
+                        # passthrough_lazy_args should generally be as innermost as possible
                         # (so that e.g. the curry decorator will see the function as lazy)
-                        tree.decorator_list.append(hq[mark_lazy])
+                        tree.decorator_list.append(hq[passthrough_lazy_args])
                     tree.body = rec(tree.body)
 
         elif type(tree) is Call:
diff --git a/unpythonic/syntax/tailtools.py b/unpythonic/syntax/tailtools.py
@@ -31,7 +31,7 @@
 from ..it import uniqify
 from ..fun import identity, orf
 from ..tco import trampolined, jump
-from ..lazyutil import mark_lazy
+from ..lazyutil import passthrough_lazy_args
 
 # -----------------------------------------------------------------------------
 # Implicit return. This performs a tail-position analysis of function bodies.
@@ -134,7 +134,7 @@ def chain_conts(cc1, cc2, with_star=False):  # cc1=_pcc, cc2=cc
     """Internal function, used in code generated by the continuations macro."""
     if with_star:  # to be chainable from a tail call, accept a multiple-values arglist
         if cc1 is not None:
-            @mark_lazy
+            @passthrough_lazy_args
             def cc(*value):
                 return jump(cc1, cc=cc2, *value)
         else:
@@ -145,14 +145,14 @@ def cc(*value):
             cc = cc2
     else:  # for inert data value returns (this produces the multiple-values arglist)
         if cc1 is not None:
-            @mark_lazy
+            @passthrough_lazy_args
             def cc(value):
                 if isinstance(value, tuple):
                     return jump(cc1, cc=cc2, *value)
                 else:
                     return jump(cc1, value, cc=cc2)
         else:
-            @mark_lazy
+            @passthrough_lazy_args
             def cc(value):
                 if isinstance(value, tuple):
                     return jump(cc2, *value)
diff --git a/unpythonic/tco.py b/unpythonic/tco.py
@@ -131,10 +131,10 @@ def baz():
 from sys import stderr
 
 from .regutil import register_decorator
-from .lazyutil import islazy, mark_lazy, maybe_force_args
+from .lazyutil import islazy, passthrough_lazy_args, maybe_force_args
 from .dynassign import dyn
 
-# In principle, jump should have @mark_lazy, but for performance reasons
+# In principle, jump should have @passthrough_lazy_args, but for performance reasons
 # it doesn't. "force(target)" is slow, so strict code shouldn't have to do that.
 # This is handled by a special case in maybe_force_args.
 def jump(target, *args, **kwargs):
@@ -284,7 +284,7 @@ def trampoline(*args, **kwargs):
             f = function
             while True:
                 if callable(f):  # the maybe_force_args here causes the performance hit
-                    v = maybe_force_args(f, *args, **kwargs)
+                    v = maybe_force_args(f, *args, **kwargs)    # <--
                 else:
                     v = f
                 if isinstance(v, _jump):
@@ -298,8 +298,11 @@ def trampoline(*args, **kwargs):
                     return v
         if callable(function):
             trampoline._entrypoint = function
-            if islazy(function):                    # <--
-                trampoline = mark_lazy(trampoline)  # <--
+            # Mark the trampolined function for passthrough of lazy args if the
+            # original function has the mark. This is needed because the mark is
+            # implemented as an attribute on the function object.
+            if islazy(function):                                # <--
+                trampoline = passthrough_lazy_args(trampoline)  # <--
             return trampoline
         else:
             return trampoline()
