parameterpack 0.1.0

Parameter Pack

This module provides a mechanism for writing something similar to C++17’s fold expressions in Python. This is achieved by co-opting Python’s mostly unused Ellipsis literal.

Supported Operators

• Addition (+)

• Subtraction (-)

• Multiplication (*)

• Integer division (//)

• Division (/)

• Modulus (%)

• Matrix Multiplication (@, Python >= 3.5 only)

• Bitwise And (&)

• Bitwise Or (|)

• Bitwise Xor (^)

• Left Shift (<<)

• Right Shift (>>)

• __call__

• Comparison operators (>, >=, <, <=, ==, !=)

Examples

There are two ways to “fold” an operation over a parameter pack: left and right folds.

from parameterpack import pack

p = pack(1, 2, 3)

# Left fold
p - ...      # (1 - 2) - 3 = -4
p - ... - 4  # ((1 - 2) - 3) - 4 = -8

# Right fold
... - p     # 1 - (2 - 3) = 2
... - p - 4 # 4 - (1 - (2 - 3)) = -2

Note that the left fold groups operations on the left, while the right fold groups them on the right. This only makes a difference if the folded operation is not associative, such as in the case of integer subtraction.

Because it is not possible to redefine the ellipsis type’s operators, a right fold on the right side of a binary operation requires parentheses.

from parameterpack import pack

p = pack(1, 2, 3)

# This is an error because "4 - ..." is evaluated first.
4 - ... - p

# This is what you should do instead.
4 - (... - p)  # 4 - (3 - (2 - 1)) = 2

You may prefer to use parentheses in every case to keep the syntax clear and avoid this potential oversight.

Conditional chains are also supported, but they work a little differently from the other folds.

from parameterpack import pack

p = pack(1, 2, 3)

# Python evaluates "a < b < c" as "a < b and b < c", so this module does the same.
p < ...      # 1 < 2 < 3 = True, so 3 is returned.
p < ... < 4  # 1 < 2 < 3 < 4 = True
p < ... < 0  # 1 < 2 < 3 < 0 = False

p = pack(3, 2, 1)

p < ...  # 3 < 2 < 1 = False, so a special False-comparing object is returned.
... < p  # 3 > 2 > 1 = True

Because python has no reversed-argument forms for the comparison operators, conditionals work a little differently. If folding the comparison over the parameter pack’s elements results in False, in order to invalidate the entire comparison chain, it will return a special object that will return False for any further comparisons. Otherwise, the last element of the parameter pack is returned so that the comparison chain can continue.

Running Tests

To run this module’s tests in your system’s Python interpreter, simply run python setup.py test from the repository root.

To run tests in all supported interpreters, first ensure that every supported Python interpreter is installed on your system and added to the PATH environment variable. Then run pip install -e .[dev] from the repository root to install development dependencies, and then run tox from the repository root to run the tests.

Bugs Reports and Feature Requests

Please use the issue tracker to submit bugs or request features.

License

Copyright Joe Lawson, 2017.

This package is distributed under the terms of the MIT license.