New method partial that behaves like functools.partial, and equivalent decorator @with_partial. Fixes #30

Author: Sylvain MARIE

docs/index.md

@@ -306,6 +306,58 @@ modified signature: (z, c, o=True)
 They might save you a few lines of code if your use-case is not too specific.
 
 
+#### Removing parameters easily
+
+As goodies, `makefun` provides a `partial` function that are equivalent to `functools.partial`, except that it is fully signature-preserving and modifies the documentation with a nice helper message explaining that this is a partial view:
+
+```python
+def foo(x, y):
+    """
+    a `foo` function
+
+    :param x:
+    :param y:
+    :return:
+    """
+    return x + y
+   
+from makefun import partial
+bar = partial(foo, x=12)
+``` 
+
+we can test it:
+
+```python
+>>> assert bar(1) == 13
+>>> help(bar)
+Help on function bar in module makefun.tests.test_partial_and_macros:
+
+bar(y)
+    <This function is equivalent to 'foo(y, x=12)', see original 'foo' doc below.>
+    
+    a `foo` function
+    
+    :param x:
+    :param y:
+    :return:
+```
+
+A decorator is also available to create partial views easily for quick tests:
+
+```python
+@with_partial(x=12)
+def foo(x, y):
+    """
+    a `foo` function
+
+    :param x:
+    :param y:
+    :return:
+    """
+    return x + y
+```
+
+
 ### 3- Advanced topics
 
 #### Generators and Coroutines

makefun/__init__.py

@@ -1,10 +1,10 @@
 from makefun.main import create_function, with_signature, remove_signature_parameters, add_signature_parameters, \
-    wraps, create_wrapper
+    wraps, create_wrapper, partial, with_partial
 
 __all__ = [
     # submodules
     'main',
     # symbols
     'create_function', 'with_signature', 'remove_signature_parameters', 'add_signature_parameters',
-    'wraps', 'create_wrapper'
+    'wraps', 'create_wrapper', 'partial', 'with_partial'
 ]

makefun/_main_latest_py.py

@@ -0,0 +1,20 @@
+from itertools import chain
+
+from makefun.main import wraps
+
+
+def make_partial_using_yield_from(new_sig, f, *preset_pos_args, **preset_kwargs):
+    """
+    Makes a 'partial' when f is a generator and python is new enough to support `yield from`
+
+    :param new_sig:
+    :param f:
+    :param presets:
+    :return:
+    """
+    @wraps(f, new_sig)
+    def partial_f(*args, **kwargs):
+        # since the signature does the checking for us, no need to check for redundancy.
+        kwargs.update(preset_kwargs)  # for python 3.4: explicit dict update
+        yield from f(*chain(preset_pos_args, args), **kwargs)
+    return partial_f

makefun/_main_legacy_py.py

@@ -1,3 +1,53 @@
+import sys
+from itertools import chain
+
+from makefun.main import wraps
+
+
+def make_partial_using_yield(new_sig, f, *preset_pos_args, **preset_kwargs):
+    """
+    Makes a 'partial' when f is a generator and python is new enough to support `yield from`
+
+    :param new_sig:
+    :param f:
+    :param preset_pos_args:
+    :param preset_kwargs:
+    :return:
+    """
+    @wraps(f, new_sig=new_sig)
+    def partial_f(*args, **kwargs):
+        # since the signature does the checking for us, no need to check for redundancy.
+        kwargs.update(preset_kwargs)
+        gen = f(*chain(preset_pos_args, args), **kwargs)
+        _i = iter(gen)  # initialize the generator
+        _y = next(_i)  # first iteration
+        while 1:
+            try:
+                _s = yield _y  # yield the first output and retrieve the new input
+            except GeneratorExit as _e:  # ---generator exit error---
+                try:
+                    _m = _i.close  # if there is a close method
+                except AttributeError:
+                    pass
+                else:
+                    _m()  # use it first
+                raise _e  # then re-raise exception
+            except BaseException as _e:  # ---other exception
+                _x = sys.exc_info()  # if captured exception, grab info
+                try:
+                    _m = _i.throw  # if there is a throw method
+                except AttributeError:
+                    raise _e  # otherwise re-raise
+                else:
+                    _y = _m(*_x)  # use it
+            else:  # --- nominal case: the new input was received
+                # if _s is None:
+                #     _y = next(_i)
+                # else:
+                _y = _i.send(_s)  # let the implementation decide if None means "no new input" or "new input = None"
+    return partial_f
+
+
 def get_legacy_py_generator_body_template():
     """
     In Python 2 we cannot use `yield from` in the generated function body.

makefun/main.py

@@ -198,15 +198,7 @@ def create_function(func_signature,             # type: Union[str, Signature]
     if inject_as_first_arg:
         params_str = "%s, %s" % (func_name, params_str)
 
-    if (3, 5) <= sys.version_info < (3, 6):
-        # with Python 3.5 isgeneratorfunction returns True for all coroutines
-        # however we know that it is NOT possible to have a generator
-        # coroutine in python 3.5: PEP525 was not there yet
-        generatorcaller = isgeneratorfunction(func_impl) and not iscoroutinefunction(func_impl)
-    else:
-        generatorcaller = isgeneratorfunction(func_impl)
-
-    if generatorcaller:
+    if _is_generator_func(func_impl):
         if sys.version_info >= (3, 3):
             body = "def %s\n    yield from _func_impl_(%s)\n" % (func_signature_str, params_str)
         else:
@@ -239,6 +231,21 @@ def create_function(func_signature,             # type: Union[str, Signature]
     return f
 
 
+def _is_generator_func(func_impl):
+    """
+    Return True if the func_impl is a generator
+    :param func_impl:
+    :return:
+    """
+    if (3, 5) <= sys.version_info < (3, 6):
+        # with Python 3.5 isgeneratorfunction returns True for all coroutines
+        # however we know that it is NOT possible to have a generator
+        # coroutine in python 3.5: PEP525 was not there yet
+        return isgeneratorfunction(func_impl) and not iscoroutinefunction(func_impl)
+    else:
+        return isgeneratorfunction(func_impl)
+
+
 class DefaultHolder:
     __slots__ = 'varname'
 
@@ -778,3 +785,74 @@ def add_signature_parameters(s,         # type: Signature
             lst.append(last)
 
     return s.replace(parameters=lst)
+
+
+def with_partial(*preset_pos_args, **preset_kwargs):
+    """
+    Decorator to 'partialize' a function using `partial`
+
+    :param preset_pos_args:
+    :param preset_kwargs:
+    :return:
+    """
+    def apply_decorator(f):
+        return partial(f, *preset_pos_args, **preset_kwargs)
+    return apply_decorator
+
+
+def partial(f, *preset_pos_args, **preset_kwargs):
+    """
+
+    :param preset_pos_args:
+    :param preset_kwargs:
+    :return:
+    """
+    # TODO do we need to mimic `partial`'s behaviour concerning positional args?
+
+    # (1) remove all preset arguments from the signature
+    orig_sig = signature(f)
+    # first the first n positional
+    if len(orig_sig.parameters) <= len(preset_pos_args):
+        raise ValueError("Cannot preset %s positional args, function %s has only %s args."
+                         "" % (len(preset_pos_args), f.__name__, len(orig_sig.parameters)))
+    new_sig = Signature(parameters=tuple(orig_sig.parameters.values())[len(preset_pos_args):],
+                        return_annotation=orig_sig.return_annotation)
+    # then the keyword
+    try:
+        new_sig = remove_signature_parameters(new_sig, *preset_kwargs.keys())
+    except KeyError as e:
+        raise ValueError("Cannot preset keyword argument, it does not appear to be present in the signature of %s: %s"
+                         "" % (f.__name__, e))
+
+    if _is_generator_func(f):
+        if sys.version_info >= (3, 3):
+            from makefun._main_latest_py import make_partial_using_yield_from
+            partial_f = make_partial_using_yield_from(new_sig, f, *preset_pos_args, **preset_kwargs)
+        else:
+            from makefun._main_legacy_py import make_partial_using_yield
+            partial_f = make_partial_using_yield(new_sig, f, *preset_pos_args, **preset_kwargs)
+    else:
+        @wraps(f, new_sig=new_sig)
+        def partial_f(*args, **kwargs):
+            # since the signature does the checking for us, no need to check for redundancy.
+            kwargs.update(preset_kwargs)
+            return f(*itertools.chain(preset_pos_args, args), **kwargs)
+
+    # update the doc
+    argstring = ', '.join([("%s" % a) for a in preset_pos_args])
+    if len(argstring) > 0:
+        argstring = argstring + ', '
+    argstring = argstring + str(new_sig)[1:-1]
+    if len(argstring) > 0:
+        argstring = argstring + ', '
+    argstring = argstring + ', '.join(["%s=%s" % (k, v) for k, v in preset_kwargs.items()])
+    new_line = "<This function is equivalent to '%s(%s)', see original '%s' doc below.>\n" \
+               "" % (partial_f.__name__, argstring, partial_f.__name__)
+    # new_line = new_line + ("-" * (len(new_line) - 1)) + '\n'
+    try:
+        doc = getattr(partial_f, '__doc__')
+        partial_f.__doc__ = new_line + doc
+    except AttributeError:
+        partial_f.__doc__ = new_line
+
+    return partial_f

makefun/tests/test_partial_and_macros.py

@@ -0,0 +1,49 @@
+from makefun import with_partial
+
+
+def test_doc():
+    def foo(x, y):
+        """
+        a `foo` function
+
+        :param x:
+        :param y:
+        :return:
+        """
+        return x + y
+
+    from makefun import partial
+    bar = partial(foo, x=12)
+    bar.__name__ = 'bar'
+    help(bar)
+    assert bar(1) == 13
+
+
+def test_partial():
+    """Tests that `with_partial` works"""
+
+    @with_partial(a='hello')
+    def foo(x, y, a):
+        """
+        a `foo` function
+
+        :param x:
+        :param y:
+        :param a:
+        :return:
+        """
+        print(a)
+        print(x, y)
+
+    foo(1, 2)
+    help(foo)
+
+    assert foo.__doc__ == """<This function is equivalent to 'foo(x, y, a=hello)', see original 'foo' doc below.>
+
+        a `foo` function
+
+        :param x:
+        :param y:
+        :param a:
+        :return:
+        """