python-graphy 1.0+dfsg-3 / usr / share / pyshared / graphy / common.py

#!/usr/bin/python2.4
#
# Copyright 2008 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Code common to all chart types."""

import copy
import warnings

from graphy import formatters
from graphy import util


class Marker(object):

  """Represents an abstract marker, without position.  You can attach these to
  a DataSeries.

  Object attributes:
    shape: One of the shape codes (Marker.arrow, Marker.diamond, etc.)
    color: color (as hex string, f.ex. '0000ff' for blue)
    size:  size of the marker
  """
  # TODO: Write an example using markers.

  # Shapes:
  arrow = 'a'
  cross = 'c'
  diamond = 'd'
  circle = 'o'
  square = 's'
  x = 'x'

  # Note: The Google Chart API also knows some other markers ('v', 'V', 'r',
  # 'b') that I think would fit better into a grid API.
  # TODO: Make such a grid API

  def __init__(self, shape, color, size):
    """Construct a Marker.  See class docstring for details on args."""
    # TODO: Shapes 'r' and 'b' would be much easier to use if they had a
    # special-purpose API (instead of trying to fake it with markers)
    self.shape = shape
    self.color = color
    self.size = size


class _BasicStyle(object):
  """Basic style object.  Used internally."""

  def __init__(self, color):
    self.color = color


class DataSeries(object):

  """Represents one data series for a chart (both data & presentation
  information).

  Object attributes:
    points:  List of numbers representing y-values (x-values are not specified
             because the Google Chart API expects even x-value spacing).
    label:   String with the series' label in the legend.  The chart will only
             have a legend if at least one series has a label.  If some series
             do not have a label then they will have an empty description in
             the legend.  This is currently a limitation in the Google Chart
             API.
    style:   A chart-type-specific style object.  (LineStyle for LineChart,
             BarsStyle for BarChart, etc.)
    markers: List of (x, m) tuples where m is a Marker object and x is the
             x-axis value to place it at.

             The "fill" markers ('r' & 'b') are a little weird because they
             aren't a point on a line.  For these, you can fake it by
             passing slightly weird data (I'd like a better API for them at
             some point):
               For 'b', you attach the marker to the starting series, and set x
               to the index of the ending line.  Size is ignored, I think.

               For 'r', you can attach to any line, specify the starting
               y-value for x and the ending y-value for size.  Y, in this case,
               is becase 0.0 (bottom) and 1.0 (top).
    color:   DEPRECATED
  """

  # TODO: Should we require the points list to be non-empty ?
  # TODO: Do markers belong here?  They are really only used for LineCharts
  def __init__(self, points, label=None, style=None, markers=None, color=None):
    """Construct a DataSeries.  See class docstring for details on args."""
    if label is not None and util._IsColor(label):
      warnings.warn('Your code may be broken! Label is a hex triplet.  Maybe '
                    'it is a color? The old argument order (color & style '
                    'before label) is deprecated.', DeprecationWarning,
                    stacklevel=2)
    if color is not None:
      warnings.warn('Passing color is deprecated.  Pass a style object '
                    'instead.', DeprecationWarning, stacklevel=2)
      # Attempt to fix it for them.  If they also passed a style, honor it.
      if style is None:
        style = _BasicStyle(color)
    if style is not None and isinstance(style, basestring):
      warnings.warn('Your code is broken! Style is a string, not an object. '
                    'Maybe you are passing a color?  Passing color is '
                    'deprecated; pass a style object instead.',
                    DeprecationWarning, stacklevel=2)
    if style is None:
      style = _BasicStyle(None)
    self.data = points
    self.style = style
    self.markers = markers or []
    self.label = label

  def _GetColor(self):
    warnings.warn('DataSeries.color is deprecated, use '
                  'DataSeries.style.color instead.', DeprecationWarning,
                  stacklevel=2)
    return self.style.color

  def _SetColor(self, color):
    warnings.warn('DataSeries.color is deprecated, use '
                  'DataSeries.style.color instead.', DeprecationWarning,
                  stacklevel=2)
    self.style.color = color

  color = property(_GetColor, _SetColor)


class AxisPosition(object):
  """Represents all the available axis positions.

  The available positions are as follows:
    AxisPosition.TOP
    AxisPosition.BOTTOM
    AxisPosition.LEFT
    AxisPosition.RIGHT
  """
  LEFT = 'y'
  RIGHT = 'r'
  BOTTOM = 'x'
  TOP = 't'


class Axis(object):

  """Represents one axis.

  Object setings:
    min:    Minimum value for the bottom or left end of the axis
    max:    Max value.
    labels: List of labels to show along the axis.
    label_positions: List of positions to show the labels at.  Uses the scale
                     set by min & max, so if you set min = 0 and max = 10, then
                     label positions [0, 5, 10] would be at the bottom,
                     middle, and top of the axis, respectively.
    grid_spacing:  Amount of space between gridlines (in min/max scale).
                   A value of 0 disables gridlines.
    label_gridlines: If True, draw a line extending from each label
                   on the axis all the way across the chart.
  """

  def __init__(self, axis_min=None, axis_max=None):
    """Construct a new Axis.

    Args:
      axis_min: smallest value on the axis
      axis_max: largest value on the axis
    """
    self.min = axis_min
    self.max = axis_max
    self.labels = []
    self.label_positions = []
    self.grid_spacing = 0
    self.label_gridlines = False

# TODO: Add other chart types.  Order of preference:
# - scatter plots
# - us/world maps

class BaseChart(object):
  """Base chart object with standard behavior for all other charts.

  Object attributes:
    data: List of DataSeries objects. Chart subtypes provide convenience
          functions (like AddLine, AddBars, AddSegment) to add more series
          later.
    left/right/bottom/top: Axis objects for the 4 different axes.
    formatters: A list of callables which will be used to format this chart for
                display.  TODO: Need better documentation for how these
                work.
    auto_scale, auto_color, auto_legend:
      These aliases let users access the default formatters without poking
      around in self.formatters.  If the user removes them from
      self.formatters then they will no longer be enabled, even though they'll
      still be accessible through the aliases.  Similarly, re-assigning the
      aliases has no effect on the contents of self.formatters.
    display: This variable is reserved for backends to populate with a display
             object.  The intention is that the display object would be used to
             render this chart.  The details of what gets put here depends on
             the specific backend you are using.
  """

  # Canonical ordering of position keys
  _POSITION_CODES = 'yrxt'

  # TODO: Add more inline args to __init__ (esp. labels).
  # TODO: Support multiple series in the constructor, if given.
  def __init__(self):
    """Construct a BaseChart object."""
    self.data = []

    self._axes = {}
    for code in self._POSITION_CODES:
      self._axes[code] = [Axis()]
    self._legend_labels = []  # AutoLegend fills this out
    self._show_legend = False  # AutoLegend fills this out

    # Aliases for default formatters
    self.auto_color = formatters.AutoColor()
    self.auto_scale = formatters.AutoScale()
    self.auto_legend = formatters.AutoLegend
    self.formatters = [self.auto_color, self.auto_scale, self.auto_legend]
    # display is used to convert the chart into something displayable (like a
    # url or img tag).
    self.display = None

  def AddFormatter(self, formatter):
    """Add a new formatter to the chart (convenience method)."""
    self.formatters.append(formatter)

  def AddSeries(self, points, color=None, style=None, markers=None,
                label=None):
    """DEPRECATED

    Add a new series of data to the chart; return the DataSeries object."""
    warnings.warn('AddSeries is deprecated.  Instead, call AddLine for '
                  'LineCharts, AddBars for BarCharts, AddSegment for '
                  'PieCharts ', DeprecationWarning, stacklevel=2)
    series = DataSeries(points, color=color, style=style, markers=markers,
                        label=label)
    self.data.append(series)
    return series

  def GetDependentAxes(self):
    """Return any dependent axes ('left' and 'right' by default for LineCharts,
    although bar charts would use 'bottom' and 'top').
    """
    return self._axes[AxisPosition.LEFT] + self._axes[AxisPosition.RIGHT]

  def GetIndependentAxes(self):
    """Return any independent axes (normally top & bottom, although horizontal
    bar charts use left & right by default).
    """
    return self._axes[AxisPosition.TOP] + self._axes[AxisPosition.BOTTOM]

  def GetDependentAxis(self):
    """Return this chart's main dependent axis (often 'left', but
    horizontal bar-charts use 'bottom').
    """
    return self.left

  def GetIndependentAxis(self):
    """Return this chart's main independent axis (often 'bottom', but
    horizontal bar-charts use 'left').
    """
    return self.bottom

  def _Clone(self):
    """Make a deep copy this chart.

    Formatters & display will be missing from the copy, due to limitations in
    deepcopy.
    """
    orig_values = {}
    # Things which deepcopy will likely choke on if it tries to copy.
    uncopyables = ['formatters', 'display', 'auto_color', 'auto_scale',
                   'auto_legend']
    for name in uncopyables:
      orig_values[name] = getattr(self, name)
      setattr(self, name, None)
    clone = copy.deepcopy(self)
    for name, orig_value in orig_values.iteritems():
      setattr(self, name, orig_value)
    return clone

  def GetFormattedChart(self):
    """Get a copy of the chart with formatting applied."""
    # Formatters need to mutate the chart, but we don't want to change it out
    # from under the user.  So, we work on a copy of the chart.
    scratchpad = self._Clone()
    for formatter in self.formatters:
      formatter(scratchpad)
    return scratchpad

  def GetMinMaxValues(self):
    """Get the largest & smallest values in this chart, returned as
    (min_value, max_value).  Takes into account complciations like stacked data
    series.

    For example, with non-stacked series, a chart with [1, 2, 3] and [4, 5, 6]
    would return (1, 6).  If the same chart was stacking the data series, it
    would return (5, 9).
    """
    MinPoint = lambda data: min(x for x in data if x is not None)
    MaxPoint = lambda data: max(x for x in data if x is not None)
    mins  = [MinPoint(series.data) for series in self.data if series.data]
    maxes = [MaxPoint(series.data) for series in self.data if series.data]
    if not mins or not maxes:
      return None, None # No data, just bail.
    return min(mins), max(maxes)

  def AddAxis(self, position, axis):
    """Add an axis to this chart in the given position.

    Args:
      position: an AxisPosition object specifying the axis's position
      axis: The axis to add, an Axis object
    Returns:
      the value of the axis parameter
    """
    self._axes.setdefault(position, []).append(axis)
    return axis

  def GetAxis(self, position):
    """Get or create the first available axis in the given position.

    This is a helper method for the left, right, top, and bottom properties.
    If the specified axis does not exist, it will be created.

    Args:
      position: the position to search for
    Returns:
      The first axis in the given position
    """
    # Not using setdefault here just in case, to avoid calling the Axis()
    # constructor needlessly
    if position in self._axes:
      return self._axes[position][0]
    else:
      axis = Axis()
      self._axes[position] = [axis]
      return axis

  def SetAxis(self, position, axis):
    """Set the first axis in the given position to the given value.

    This is a helper method for the left, right, top, and bottom properties.

    Args:
      position: an AxisPosition object specifying the axis's position
      axis: The axis to set, an Axis object
    Returns:
      the value of the axis parameter
    """
    self._axes.setdefault(position, [None])[0] = axis
    return axis

  def _GetAxes(self):
    """Return a generator of (position_code, Axis) tuples for this chart's axes.

    The axes will be sorted by position using the canonical ordering sequence,
    _POSITION_CODES.
    """
    for code in self._POSITION_CODES:
      for axis in self._axes.get(code, []):
        yield (code, axis)

  def _GetBottom(self):
    return self.GetAxis(AxisPosition.BOTTOM)

  def _SetBottom(self, value):
    self.SetAxis(AxisPosition.BOTTOM, value)

  bottom = property(_GetBottom, _SetBottom,
                    doc="""Get or set the bottom axis""")

  def _GetLeft(self):
    return self.GetAxis(AxisPosition.LEFT)

  def _SetLeft(self, value):
    self.SetAxis(AxisPosition.LEFT, value)

  left = property(_GetLeft, _SetLeft,
                  doc="""Get or set the left axis""")

  def _GetRight(self):
    return self.GetAxis(AxisPosition.RIGHT)

  def _SetRight(self, value):
    self.SetAxis(AxisPosition.RIGHT, value)

  right = property(_GetRight, _SetRight,
                   doc="""Get or set the right axis""")

  def _GetTop(self):
    return self.GetAxis(AxisPosition.TOP)

  def _SetTop(self, value):
    self.SetAxis(AxisPosition.TOP, value)

  top = property(_GetTop, _SetTop,
                 doc="""Get or set the top axis""")