New star

[ForeverWintr]

The culmination of a couple of weeks of experimentation, this adds the star metafunction decorator.

star simply calls the wrapped metafunction with *args instead of args. It's analogous to
lambda args, **kwargs: metafunction(*args, **kwargs).

Why:

Every function in python returns a single python object (return 1, 2 is returning a tuple). That means that within a pipeline, every function after the initial function will receive only a single arg. My goal has been to find a way to allow a function to receive multiple positional arguments. There are several reasons I think this is worthwhile:

1. It allows passing the results of multiple functions to a single function, without having to modify the receiving function's signature:

   @node
   def f(result1, result2):
       ...
   cmp = (a & b) | star(f)

2. It provides a corresponding 'split' to the 'merge' that FunctionMerge provides. If we consider 3 separate MetaFunctions a, b, and c (presumably each consisting of multiple functions), we can merge the results of those functions with m = (a & b & c) (the & operator is arbitrary, we could also have used another FunctionMerge). Thanks to the FunctionMerge call signature introduced in Merge call signature #8, we can split our input, providing different arguments to a, b, and c, by calling

   m(1, 2, 3) # <- equivalent to (a(1), b(2), c(3))

   However, that only works if cmp is the first function called. Consider the case where the merge in cmp appears later in the pipeline:

   cmp2 = func1 | m  # <- equivalent to func1 | (a & b & c)

   Even if func1 returns an iterable, that iterable arrives in the FunctionMerge as a single argument, and so the entire iterable is passed to each of a, b, and c. star solves this problem by allowing us to expand the iterable before it arrives in m.

3. It allows us to apply this split anywhere, even if there are no operators involved. I originally tried to solve the star expansion problem using a 'broadcast operator' (@, introduced in Broadcast #7), but that approach doesn't work when the functions that need star expansion are within a FunctionMerge. star does.

   expanded = (star(a) + star(b))
   expanded([1, 2], [3, 4]) # <- equivalent to a(1, 2) + b(3, 4)

[codecov]

Codecov Report

Merging #9 into dev will decrease coverage by 1.08%.
The diff coverage is 86.95%.

@@            Coverage Diff             @@
##              dev       #9      +/-   ##
==========================================
- Coverage   94.93%   93.85%   -1.09%     
==========================================
  Files           9        9              
  Lines         296      309      +13     
  Branches       27       30       +3     
==========================================
+ Hits          281      290       +9     
- Misses         12       15       +3     
- Partials        3        4       +1

Impacted Files	Coverage Δ
metafunctions/util.py	96.77% <100%> (+0.34%)	⬆️
metafunctions/core/_base.py	99.33% <100%> (-0.03%)	⬇️
metafunctions/concurrent.py	71.42% <64.7%> (-1.3%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a00145c...38685ed. Read the comment docs.

[codecov]

Codecov Report

Merging #9 into dev will decrease coverage by 0.77%.
The diff coverage is 87.23%.

@@            Coverage Diff             @@
##              dev       #9      +/-   ##
==========================================
- Coverage   94.93%   94.15%   -0.78%     
==========================================
  Files           9        9              
  Lines         296      308      +12     
  Branches       27       29       +2     
==========================================
+ Hits          281      290       +9     
- Misses         12       15       +3     
  Partials        3        3

Impacted Files	Coverage Δ
metafunctions/core/_base.py	100% <100%> (+0.64%)	⬆️
metafunctions/util.py	96.77% <100%> (+0.34%)	⬆️
metafunctions/concurrent.py	71.42% <64.7%> (-1.3%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a00145c...1c61911. Read the comment docs.

[ForeverWintr]

This decreases code coverage because it adds a line to the code that is only executed in a fork, which codecov still isn't picking up properly. 😞