Merge pull request #18 from tacaswell/doc_defaultdict

TST/Doc

Author: jenshnielsen

doc/source/index.rst

@@ -245,6 +245,45 @@ We can use `Cycler` instances to cycle over one or more ``kwarg`` to
       ax2.plot(x, x*(i+1), **sty)
 
 
+Persistent Cycles
+-----------------
+
+It can be useful to associate a given label with a style via
+dictionary lookup and to dynamically generate that mapping.  This
+can easily be accomplished using a `~collections.defaultdict`
+
+.. ipython:: python
+
+   from cycler import cycler as cy
+   from collections import defaultdict
+
+   cyl = cy('c', 'rgb') + cy('lw', range(1, 4))
+
+To get a finite set of styles
+
+.. ipython:: python
+
+   finite_cy_iter = iter(cyl)
+   dd_finite = defaultdict(lambda : next(finite_cy_iter))
+
+or repeating
+
+.. ipython:: python
+
+   loop_cy_iter = cyl()
+   dd_loop = defaultdict(lambda : next(loop_cy_iter))
+
+This can be helpful when plotting complex data which has both a classification
+and a label ::
+
+  finite_cy_iter = iter(cyl)
+  styles = defaultdict(lambda : next(finite_cy_iter))
+  for group, label, data in DataSet:
+      ax.plot(data, label=label, **styles[group])
+
+which will result in every ``data`` with the same ``group`` being plotted with
+the same style.
+
 Exceptions
 ----------
 

test_cycler.py

@@ -186,7 +186,7 @@ def test_copying():
     i2 = ['r', 'g', 'b']
     # For more mutation fun!
     i3 = [['y', 'g'], ['b', 'k']]
-    
+
     c1 = cycler('c', i1)
     c2 = cycler('lw', i2)
     c3 = cycler('foo', i3)
@@ -265,3 +265,17 @@ def test_eq():
     yield _eq_test_helper, a, c, False
     d = cycler(c='ymk')
     yield _eq_test_helper, b, d, False
+
+
+def test_cycler_exceptions():
+    assert_raises(TypeError, cycler)
+    assert_raises(TypeError, cycler, 'c', 'rgb', lw=range(3))
+    assert_raises(TypeError, cycler, 'c')
+    assert_raises(TypeError, cycler, 'c', 'rgb', 'lw', range(3))
+
+
+def test_starange_init():
+    c = cycler('r', 'rgb')
+    c2 = cycler('lw', range(3))
+    cy = Cycler(list(c), list(c2), zip)
+    assert_equal(cy, c + c2)