[API] Change the cycler() form to be kwargs only.

* Update documentation
* Update tests

Author: WeatherGod

cycler.py

@@ -7,8 +7,8 @@
 You can add cyclers::
 
     from cycler import cycler
-    cc = (cycler('color', list('rgb')) +
-          cycler('linestyle', ['-', '--', '-.']))
+    cc = (cycler(color=list('rgb')) +
+          cycler(linestyle=['-', '--', '-.']))
     for d in cc:
         print(d)
 
@@ -22,8 +22,8 @@
 You can multiply cyclers::
 
     from cycler import cycler
-    cc = (cycler('color', list('rgb')) *
-          cycler('linestyle', ['-', '--', '-.']))
+    cc = (cycler(color=list('rgb')) *
+          cycler(linestyle=['-', '--', '-.']))
     for d in cc:
         print(d)
 
@@ -164,8 +164,8 @@ def __getitem__(self, key):
         # TODO : maybe add numpy style fancy slicing
         if isinstance(key, slice):
             trans = self._transpose()
-            return reduce(add, (cycler(k, v[key])
-                                for k, v in six.iteritems(trans)))
+            return cycler(**dict((k, v[key])
+                                 for k, v in six.iteritems(trans)))
         else:
             raise ValueError("Can only use slices with Cycler.__getitem__")
 
@@ -203,8 +203,8 @@ def __mul__(self, other):
             return Cycler(self, other, product)
         elif isinstance(other, int):
             trans = self._transpose()
-            return reduce(add, (cycler(k, v*other)
-                                for k, v in six.iteritems(trans)))
+            return cycler(**dict((k, v*other)
+                                 for k, v in six.iteritems(trans)))
         else:
             return NotImplemented
 
@@ -268,7 +268,7 @@ def __repr__(self):
         if self._right is None:
             lab = self.keys.pop()
             itr = list(v[lab] for v in self)
-            return "cycler({lab!r}, {itr!r})".format(lab=lab, itr=itr)
+            return "cycler({lab}={itr!r})".format(lab=lab, itr=itr)
         else:
             op = op_map.get(self._op, '?')
             msg = "({left!r} {op} {right!r})"
@@ -329,7 +329,7 @@ def simplify(self):
         # I would believe that there is some performance implications
 
         trans = self._transpose()
-        return reduce(add, (cycler(k, v) for k, v in six.iteritems(trans)))
+        return cycler(**dict((k, v) for k, v in six.iteritems(trans)))
 
 
 def cycler(*args, **kwargs):
@@ -338,13 +338,10 @@ def cycler(*args, **kwargs):
     positional arguments or keyword arguments.
 
     cycler(arg)
-    cycler(label1, itr1[, label2, iter2[, ...]])
     cycler(label1=itr1[, label2=iter2[, ...]])
 
     Form 1 simply copies a given `Cycler` object.
-    Form 2 composes a `Cycler` as an outer product of the
-    pairs of label/iter.
-    Form 3 composes a `Cycler` as an inner product of the
+    Form 2 composes a `Cycler` as an inner product of the
     pairs of keyword arguments.
 
     Parameters
@@ -359,31 +356,25 @@ def cycler(*args, **kwargs):
     -------
     cycler : Cycler
         New `Cycler` for the given property
-    """
 
+    """
     if args and kwargs:
         raise TypeError("cyl() can only accept positional OR keyword "
                         "arguments -- not both.")
-    elif not args and not kwargs:
-        raise TypeError("cyl() must have positional OR keyword arguments")
 
     if len(args) == 1:
         if not isinstance(args[0], Cycler):
             raise TypeError("If only one positional argument given, it must "
                             " be a Cycler instance.")
         return copy.copy(args[0])
     elif len(args) > 1:
-        if (len(args) % 2) == 1:
-            raise TypeError("Positional arguments must be in pairs. Odd "
-                            " number of arguments found: %d" % len(args))
-        pairs = [(args[i], args[i+1]) for i in range(0, len(args), 2)]
-        op = mul
+        raise TypeError("Only a single Cycler can be accepted as the lone "
+                        "positional argument. Use keyword arguments instead.")
 
     if kwargs:
-        pairs = six.iteritems(kwargs)
-        op = add
+        return reduce(add, (_cycler(k, v) for k, v in six.iteritems(kwargs)))
 
-    return reduce(op, (_cycler(k, v) for k, v in pairs))
+    raise TypeError("Must have at least a positional OR keyword arguments")
 
 
 def _cycler(label, itr):

doc/source/index.rst

@@ -42,7 +42,7 @@ hashable (as it will eventually be used as the key in a :obj:`dict`).
    from cycler import cycler
 
 
-   color_cycle = cycler('color', ['r', 'g', 'b'])
+   color_cycle = cycler(color=['r', 'g', 'b'])
    color_cycle
 
 The `Cycler` knows it's length and keys:
@@ -61,12 +61,12 @@ the label
    for v in color_cycle:
        print(v)
 
-`Cycler` objects can be passed as the second argument to :func:`cycler`
+`Cycler` objects can be passed as the argument to :func:`cycler`
 which returns a new  `Cycler` with a new label, but the same values.
 
 .. ipython:: python
 
-   cycler('ec', color_cycle)
+   cycler(ec=color_cycle)
 
 
 Iterating over a `Cycler` results in the finite list of entries, to
@@ -94,12 +94,12 @@ Equal length `Cycler` s with different keys can be added to get the
 
 .. ipython:: python
 
-   lw_cycle = cycler('lw', range(1, 4))
+   lw_cycle = cycler(lw=range(1, 4))
 
    wc = lw_cycle + color_cycle
 
 The result has the same length and has keys which are the union of the
-two input `Cycler` s.
+two input `Cycler`'s.
 
 .. ipython:: python
 
@@ -123,6 +123,17 @@ As with arithmetic, addition is commutative
    for j, (a, b) in enumerate(zip(lw_c, c_lw)):
       print('({j}) A: {A!r} B: {B!r}'.format(j=j, A=a, B=b))
 
+For convenience, the :func:`cycler` function can have multiple
+key-value pairs and will automatically compose them into a single
+`Cycler` via addition
+
+.. ipython:: python
+
+    wc = cycler(c=['r', 'g', 'b'], lw=range(3))
+
+    for s in wc:
+        print(s)
+
 
 Multiplication
 ~~~~~~~~~~~~~~
@@ -131,7 +142,7 @@ Any pair of `Cycler` can be multiplied
 
 .. ipython:: python
 
-   m_cycle = cycler('marker', ['s', 'o'])
+   m_cycle = cycler(marker=['s', 'o'])
 
    m_c = m_cycle * color_cycle
 
@@ -199,7 +210,7 @@ We can use `Cycler` instances to cycle over one or more ``kwarg`` to
                                   figsize=(8, 4))
    x = np.arange(10)
 
-   color_cycle = cycler('c', ['r', 'g', 'b'])
+   color_cycle = cycler(c=['r', 'g', 'b'])
 
    for i, sty in enumerate(color_cycle):
       ax1.plot(x, x*(i+1), **sty)
@@ -219,7 +230,7 @@ We can use `Cycler` instances to cycle over one or more ``kwarg`` to
                                   figsize=(8, 4))
    x = np.arange(10)
 
-   color_cycle = cycler('c', ['r', 'g', 'b'])
+   color_cycle = cycler(c=['r', 'g', 'b'])
    ls_cycle = cycler('ls', ['-', '--'])
    lw_cycle = cycler('lw', range(1, 4))
 
@@ -243,14 +254,14 @@ A :obj:`ValueError` is raised if unequal length `Cycler` s are added together
 .. ipython:: python
    :okexcept:
 
-   cycler('c', ['r', 'g', 'b']) + cycler('ls', ['-', '--'])
+   cycler(c=['r', 'g', 'b']) + cycler(ls=['-', '--'])
 
 or if two cycles which have overlapping keys are composed
 
 .. ipython:: python
    :okexcept:
 
-   color_cycle = cycler('c', ['r', 'g', 'b'])
+   color_cycle = cycler(c=['r', 'g', 'b'])
 
    color_cycle + color_cycle