Specify style_function. Closes #45.

docs/api/series.rst

@@ -6,3 +6,5 @@ Series
     :no-members:
 
 .. autoclass:: leather.Series
+
+.. autofunction:: leather.key_function

docs/api/shapes.rst

@@ -14,3 +14,5 @@ Shapes
 .. autoclass:: leather.Dots
 
 .. autoclass:: leather.Lines
+
+.. autofunction:: leather.style_function

docs/examples.rst

@@ -2,8 +2,8 @@
 Examples
 ========
 
-Data
-====
+Data series
+===========
 
 Simple pairs
 ------------
@@ -42,6 +42,13 @@ Custom data
 
 TKTK
 
+Multiple series
+---------------
+
+Multiple data series can be displayed on a single chart.
+
+TKTK
+
 Shapes
 ======
 
@@ -115,6 +122,8 @@ TKTK
 Styling data based on value
 ---------------------------
 
+Style attributes of individual data points can be set by value using a :func:`.style_function`.
+
 .. literalinclude:: ../examples/colorized_dots.py
     :language: python
 

examples/colorized_dots.py

@@ -5,7 +5,7 @@
 
 dot_data = [(random.randint(0, 250), random.randint(0, 250)) for i in range(100)]
 
-def colorizer(x, y, i):
+def colorizer(x, y, row, i):
     return 'rgb(%i, %i, %i)' % (x, y, 150)
 
 chart = leather.Chart('Colorized dots')

leather/__init__.py

@@ -7,6 +7,6 @@
 from leather.lattice import Lattice
 from leather.legend import Legend
 from leather.scales import Scale, Linear, Ordinal, Temporal
-from leather.series import Series
-from leather.shapes import Shape, Bars, Columns, Dots, Lines
+from leather.series import Series, key_function
+from leather.shapes import Shape, Bars, Columns, Dots, Lines, style_function
 from leather import theme

leather/shapes/__init__.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-from leather.shapes.base import Shape
+from leather.shapes.base import Shape, style_function
 from leather.shapes.bars import Bars
 from leather.shapes.columns import Columns
 from leather.shapes.dots import Dots

leather/shapes/bars.py

@@ -12,9 +12,8 @@ class Bars(Shape):
     Render a series of data as bars.
 
     :param color:
-        The color to fill the bars. You may also specify a function, which will
-        be called with the arguments :code:`(x, y, index)` and should return a
-        color.
+        The color to fill the bars. You may also specify a
+        :func:`.style_function`.
     """
     def __init__(self, color):
         self._color = color
@@ -34,7 +33,7 @@ def to_svg(self, width, height, x_scale, y_scale, series):
             y1, y2 = y_scale.project_interval(y, height, 0)
 
             if callable(self._color):
-                color = self._color(x, y, i)
+                color = self._color(x, y, row, i)
             else:
                 color = self._color
 

leather/shapes/base.py

@@ -6,3 +6,23 @@ class Shape(object):
     Base class for shapes that can be used to render data :class:`.Series`.
     """
     pass
+
+
+def style_function(x, y, row, index):
+    """
+    This example shows how to define a function to specify style values for
+    individual data points.
+
+    :param x:
+        The function will be called with the X and Y values from the data.
+    :param y:
+        See :code:`x`.
+    :param row:
+        The entire data row will also be passed in, allowing styling based on
+        non-coordinate attributes.
+    :param index:
+        The row index in the series data will also be provided.
+    :returns:
+        An appropriate value for the attribute being styled.
+    """
+    pass

leather/shapes/columns.py

@@ -12,9 +12,8 @@ class Columns(Shape):
     Render a series of data as columns.
 
     :param color:
-        The color to fill the columns. You may also specify a function, which
-        will be called with the arguments :code:`(x, y, index)` and should
-        return a color.
+        The color to fill the columns. You may also specify a
+        :func:`.style_function`.
     """
     def __init__(self, color):
         self._color = color
@@ -34,7 +33,7 @@ def to_svg(self, width, height, x_scale, y_scale, series):
             proj_y = y_scale.project(y, height, 0)
 
             if callable(self._color):
-                color = self._color(x, y, i)
+                color = self._color(x, y, row, i)
             else:
                 color = self._color
 

leather/shapes/dots.py

@@ -13,14 +13,12 @@ class Dots(Shape):
     Render a series of data as dots.
 
     :param fill_color:
-        The color to fill the dots. You may also specify a function, which will
-        be called with the arguments :code:`(x, y, index)` and should return a
-        color.
+        The color to fill the dots. You may also specify a
+        :func:`.style_function`.
     :param radius:
         The radius of the rendered dots. Defaults to
-        :data:`.theme.default_dot_radius`. You may also specify a function,
-        which will be called with the arguments :code:`(x, y, index)` and
-        should return a radius.
+        :data:`.theme.default_dot_radius`. You may also specify a
+        :func:`.style_function`.
     """
     def __init__(self, fill_color, radius=None):
         self._fill_color = fill_color
@@ -41,7 +39,7 @@ def to_svg(self, width, height, x_scale, y_scale, series):
             proj_y = y_scale.project(y, height, 0)
 
             if callable(self._fill_color):
-                fill_color = self._fill_color(x, y, i)
+                fill_color = self._fill_color(x, y, row, i)
             else:
                 fill_color = self._fill_color