Be stricter about kwargs to Mv.__init__ (#97)

Also add much better documentation for construction

Author: eric-wieser

galgebra/deprecated.py

@@ -38,8 +38,11 @@ def setup(basis, metric=None, coords=None, rframe=False, debug=False, curv=(None
             return list(MV.GA.mv())
 
 
-    def __init__(self, base, mvtype, fct=False, blade_rep=True):
-        Mv.__init__(self, base, mvtype, f=fct, ga=MV.GA)
+    def __init__(self, base, mvtype, fct=None, blade_rep=True):
+        kwargs = {}
+        if fct is not None:
+            kwargs['f'] = fct  # only forward this argument if we received it
+        Mv.__init__(self, base, mvtype, ga=MV.GA, **kwargs)
 
     def Fmt(self, fmt=1, title=None):
         print(Mv.Fmt(self, fmt=fmt, title=title))

galgebra/mv.py

@@ -19,6 +19,7 @@
 from . import metric
 from . import utils
 from .printer import ZERO_STR
+from .utils import _KwargParser
 
 ONE = S(1)
 ZERO = S(0)
@@ -61,10 +62,6 @@ class Mv(object):
     fmt = 1
     latex_flg = False
     restore = False
-    init_slots = {'f': (False, 'True if function of coordinates'),
-                  'ga': (None, 'Geometric algebra to be used with multivectors'),
-                  'coords': (None, 'Coordinates to be used with multivector function'),
-                  'recp': (None, 'Normalization for reciprocal vector')}
     dual_mode_lst = ['+I','I+','+Iinv','Iinv+','-I','I-','-Iinv','Iinv-']
 
     @staticmethod
@@ -178,9 +175,11 @@ def add_superscript(root, s):
                 return root
             return '{}__{}'.format(root, s)
         grade = __grade
+        kw = _KwargParser('_make_grade', kwargs)
         if utils.isstr(__name_or_coeffs):
             name = __name_or_coeffs
-            f = kwargs['f']
+            f = kw.pop('f', False)
+            kw.reject_remaining()
             if isinstance(f, bool):
                 if f:  # Is a multivector function of all coordinates
                     return sum([Function(add_superscript(name, super_script), real=True)(*ga.coords) * base
@@ -193,6 +192,7 @@ def add_superscript(root, s):
                             for (super_script, base) in zip(ga.blade_super_scripts[grade], ga.blades[grade])])
         elif isinstance(__name_or_coeffs, (list, tuple)):
             coeffs = __name_or_coeffs
+            kw.reject_remaining()
             if len(coeffs) <= len(ga.blades[grade]):
                 return sum([coef * base
                     for (coef, base) in zip(coeffs, ga.blades[grade][:len(coeffs)])])
@@ -259,14 +259,74 @@ def _make_odd(ga, __name_or_coeffs, **kwargs):
     _make_even = _make_spinor
 
     def __init__(self, *args, **kwargs):
+        """
+        __init__(self, *args, ga, recp=None, **kwargs)
+
+        Note this constructor is overloaded, based on the type and number of
+        positional arguments:
+
+        .. class:: Mv(*, ga, recp=None)
+
+            Create a zero multivector
+        .. class:: Mv(expr, /, *, ga, recp=None)
+
+            Create a multivector from an existing vector or sympy expression
+        .. class:: Mv(coeffs, grade, /, ga, recp=None)
+
+            Create a multivector constant with a given grade
+        .. class:: Mv(name, category, /, *cat_args, ga, recp=None, f=False)
+
+            Create a multivector constant with a given category
+        .. class:: Mv(name, grade, /, ga, recp=None, f=False)
 
-        if 'ga' not in kwargs:
-            raise ValueError("Geometric algebra key inplut 'ga' required")
+            Create a multivector variable or function of a given grade
+        .. class:: Mv(coeffs, category, /, *cat_args, ga, recp=None)
 
-        kwargs = metric.test_init_slots(Mv.init_slots, **kwargs)
+            Create a multivector variable or function of a given category
 
-        self.Ga = kwargs.pop('ga')
-        self.recp = kwargs.pop('recp')  # Normalization for reciprocal vectors
+
+        ``*`` and ``/`` in the signatures above are python
+        3.8 syntax, and respectively indicate the boundaries between
+        positional-only, normal, and keyword-only arguments.
+
+        Parameters
+        ----------
+        ga : ~galgebra.ga.Ga
+            Geometric algebra to be used with multivectors
+        recp : object, optional
+            Normalization for reciprocal vector. Unused.
+        name : str
+            Name of this multivector, if it is a variable or function
+        coeffs : sequence
+            Sequence of coefficients for the given category.
+            This is only meaningful
+        category : str
+            One of:
+
+             * ``"grade"`` - this takes an additional argument, the grade to
+               create, in ``cat_args``
+             * ``"scalar"``
+             * ``"vector"``
+             * ``"bivector"`` / ``"grade2"``
+             * ``"pseudo"``
+             * ``"mv"``
+             * ``"even"`` / ``"spinor"``
+             * ``"odd"``
+
+        f : bool, tuple
+            True if function of coordinates, or a tuple of those coordinates.
+            Only valid if a name is passed
+
+        coords :
+            This argument is always accepted but ignored.
+
+            It is incorrectly described internally as the coordinates to be
+            used with multivector functions.
+        """
+        kw = _KwargParser('__init__', kwargs)
+        self.Ga = kw.pop('ga')
+        self.recp = kw.pop('recp', None)  # not used
+        kw.pop('coords', None)  # ignored
 
         self.char_Mv = False
         self.i_grade = None  # if pure grade mv, grade value
@@ -280,6 +340,7 @@ def __init__(self, *args, **kwargs):
         if len(args) == 0:  # default constructor 0
             self.obj = S(0)
             self.i_grade = 0
+            kw.reject_remaining()
         elif len(args) == 1 and not utils.isstr(args[0]):  # copy constructor
             x = args[0]
             if isinstance(x, Mv):
@@ -293,6 +354,7 @@ def __init__(self, *args, **kwargs):
                     self.obj = S(x)
                 self.is_blade_rep = True
                 self.characterise_Mv()
+            kw.reject_remaining()
         else:
             if utils.isstr(args[1]):
                 make_args = list(args)

galgebra/utils.py

@@ -32,3 +32,45 @@ def flatten(x):
 
 def isstr(s):
     return isinstance(s, string_types)
+
+
+class _KwargParser:
+    """
+    Helper function to emulate Python 3 keyword-only arguments.
+
+    Use as::
+
+        def func(x1, **kwargs):
+            kw = KwargParser('func', kwargs)
+            a = kw.pop('a')
+            b = kw.pop('b', 2)
+            kw.reject_remaining()
+            ...
+
+    To emulate the Python 3 syntax::
+
+        def func(x1, *, a, b=2):
+            ...
+    """
+    def __init__(self, func_name, kwargs):
+        self._func_name = func_name
+        self._kwargs = kwargs
+
+    def pop(self, arg_name, *default):
+        try:
+            return self._kwargs.pop(arg_name, *default)
+        except KeyError:
+            pass
+        raise TypeError(
+            '{}() missing required keyword-only argument {!r}'
+            .format(self._func_name, arg_name)
+        )
+
+    def reject_remaining(self):
+        if self._kwargs:
+            # match the error message to what Python 3 produces
+            bad_arg = next(iter(self._kwargs))
+            raise TypeError(
+                '{}() got an unexpected keyword argument {!r}'
+                .format(self._func_name, bad_arg)
+            )

test/test_mv.py

@@ -108,8 +108,15 @@ def check(x, expected_grades):
         check(ga.mv('A', 'odd'), [1, 3])
         check(ga.mv('A', 'mv'), [0, 1, 2, 3])
 
+        # value construction
+        check(ga.mv([1, 2, 3], 'vector'), [1])
+
         # illegal arguments
         with self.assertRaises(TypeError):
             ga.mv('A', 'vector', "too many arguments")
         with self.assertRaises(TypeError):
             ga.mv('A', 'grade')  # too few arguments
+        with self.assertRaises(TypeError):
+            ga.mv('A', 'grade', not_an_argument=True)  # invalid kwarg
+        with self.assertRaises(TypeError):
+            ga.mv([1, 2, 3], 'vector', f=True)  # can't pass f with coefficients