Revision: 5622
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5622&view=rev
Author: mdboom
Date: 2008-06-20 12:46:05 -0700 (Fri, 20 Jun 2008)
Log Message:
-----------
Lots more docstring formatting.
Modified Paths:
--------------
trunk/matplotlib/lib/matplotlib/artist.py
trunk/matplotlib/lib/matplotlib/lines.py
trunk/matplotlib/lib/matplotlib/patches.py
trunk/matplotlib/lib/matplotlib/text.py
Modified: trunk/matplotlib/lib/matplotlib/artist.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/artist.py 2008-06-20 18:43:08 UTC (rev 5621)
+++ trunk/matplotlib/lib/matplotlib/artist.py 2008-06-20 19:46:05 UTC (rev 5622)
@@ -268,12 +268,16 @@
return self.figure is not None
def get_figure(self):
- 'return the figure instance'
+ """
+ Return the :class:`~matplotlib.figure.Figure` instance the
+ artist belongs to.
+ """
return self.figure
def set_figure(self, fig):
"""
- Set the figure instance the artist belong to
+ Set the :class:`~matplotlib.figure.Figure` instance the artist
+ belongs to.
ACCEPTS: a matplotlib.figure.Figure instance
"""
@@ -476,7 +480,7 @@
self.pchanged()
def update_from(self, other):
- 'copy properties from other to self'
+ 'Copy properties from *other* to *self*.'
self._transform = other._transform
self._transformSet = other._transformSet
self._visible = other._visible
@@ -504,15 +508,17 @@
class ArtistInspector:
"""
- A helper class to inspect an Artist and return information about
- it's settable properties and their current values
+ A helper class to inspect an :class:`~matplotlib.artist.Artist`
+ and return information about it's settable properties and their
+ current values.
"""
def __init__(self, o):
"""
- Initialize the artist inspector with an artist or sequence of
- artists. Id a sequence is used, we assume it is a homogeneous
- sequence (all Artists are of the same type) and it is your
- responsibility to make sure this is so.
+ Initialize the artist inspector with an
+ :class:`~matplotlib.artist.Artist` or sequence of
+ :class:`Artists`. If a sequence is used, we assume it is a
+ homogeneous sequence (all :class:`Artists` are of the same
+ type) and it is your responsibility to make sure this is so.
"""
if cbook.iterable(o) and len(o): o = o[0]
self.o = o
@@ -520,9 +526,11 @@
def get_aliases(self):
"""
- get a dict mapping fullname -> alias for each alias in o.
- Eg for lines::
+ Get a dict mapping *fullname* -> *alias* for each alias in the
+ :class:`~matplotlib.artist.ArtistInspector`.
+ Eg., for lines::
+
{'markerfacecolor': 'mfc',
'linewidth' : 'lw',
}
@@ -543,12 +551,12 @@
_get_valid_values_regex = re.compile(r"\n\s*ACCEPTS:\s*(.*)\n")
def get_valid_values(self, attr):
"""
- get the legal arguments for the setter associated with attr
+ Get the legal arguments for the setter associated with *attr*.
- This is done by querying the doc string of the function set_attr
+ This is done by querying the docstring of the function set_ *attr*
for a line that begins with ACCEPTS:
- Eg, for a line linestyle, return
+ Eg., for a line linestyle, return
[ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]
"""
@@ -570,8 +578,8 @@
def get_setters(self):
"""
- Get the attribute strings with setters for object h. Eg, for a line,
- return ['markerfacecolor', 'linewidth', ....]
+ Get the attribute strings with setters for object. Eg., for a line,
+ return ``['markerfacecolor', 'linewidth', ....]``.
"""
setters = []
@@ -585,7 +593,10 @@
return setters
def is_alias(self, o):
- 'return true if method object o is an alias for another function'
+ """
+ Return *True* if method object *o* is an alias for another
+ function.
+ """
ds = o.__doc__
if ds is None: return False
return ds.startswith('alias for ')
@@ -605,12 +616,12 @@
def pprint_setters(self, prop=None, leadingspace=2):
"""
- if prop is None, return a list of strings of all settable properies
- and their valid values
+ If *prop* is *None*, return a list of strings of all settable properies
+ and their valid values.
- if prop is not None, it is a valid property name and that
+ If *prop* is not *None*, it is a valid property name and that
property will be returned as a string of property : valid
- values
+ values.
"""
if leadingspace:
pad = ' '*leadingspace
@@ -655,7 +666,7 @@
def pprint_getters(self):
"""
- return the getters and actual values as list of strings'
+ Return the getters and actual values as list of strings.
"""
getters = [name for name in dir(self.o)
if name.startswith('get_')
@@ -678,6 +689,8 @@
def getp(o, *args):
"""
+ .. TODO: What are 's' and 'h' arguments described below?
+
Return the value of handle property s
h is an instance of a class, eg a Line2D or an Axes or Text.
@@ -751,8 +764,8 @@
with python kwargs. For example, the following are equivalent
>>> setp(lines, 'linewidth', 2, 'color', r') # matlab style
+
>>> setp(lines, linewidth=2, color='r') # python style
-
"""
insp = ArtistInspector(h)
Modified: trunk/matplotlib/lib/matplotlib/lines.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/lines.py 2008-06-20 18:43:08 UTC (rev 5621)
+++ trunk/matplotlib/lib/matplotlib/lines.py 2008-06-20 19:46:05 UTC (rev 5622)
@@ -11,7 +11,7 @@
from matplotlib import verbose
import artist
from artist import Artist
-from cbook import iterable, is_string_like, is_numlike, ls_mapper
+from cbook import iterable, is_string_like, is_numlike, ls_mapper, dedent
from colors import colorConverter
from path import Path
from transforms import Affine2D, Bbox, TransformedPath
@@ -25,34 +25,34 @@
# COVERAGE NOTE: Never called internally or from examples
def unmasked_index_ranges(mask, compressed = True):
'''
- Calculate the good data ranges in a masked 1-D np.array, based on mask.
+ Calculate the good data ranges in a masked 1-D np.array, based on
+ mask.
- Returns Nx2 np.array with each row the start and stop indices
- for slices of the compressed np.array corresponding to each of N
- uninterrupted runs of unmasked values.
- If optional argument compressed is False, it returns the
- start and stop indices into the original np.array, not the
- compressed np.array.
- Returns None if there are no unmasked values.
+ Returns Nx2 :class:`numpy.array` with each row the start and stop
+ indices for slices of the compressed :class:`numpy.array`
+ corresponding to each of *N* uninterrupted runs of unmasked
+ values. If optional argument *compressed* is *False*, it returns
+ the start and stop indices into the original :class:`numpy.array`,
+ not the compressed :class:`numpy.array`. Returns *None* if there
+ are no unmasked values.
- Example:
+ Example::
- y = ma.array(np.arange(5), mask = [0,0,1,0,0])
- #ii = unmasked_index_ranges(y.mask())
- ii = unmasked_index_ranges(ma.getmask(y))
- # returns [[0,2,] [2,4,]]
+ y = ma.array(np.arange(5), mask = [0,0,1,0,0])
+ #ii = unmasked_index_ranges(y.mask())
+ ii = unmasked_index_ranges(ma.getmask(y))
+ # returns [[0,2,] [2,4,]]
- y.compressed().filled()[ii[1,0]:ii[1,1]]
- # returns np.array [3,4,]
- # (The 'filled()' method converts the masked np.array to a numerix np.array.)
+ y.compressed().filled()[ii[1,0]:ii[1,1]]
+ # returns np.array [3,4,]
+ # (The 'filled()' method converts the masked np.array to a numerix np.array.)
- #i0, i1 = unmasked_index_ranges(y.mask(), compressed=False)
- i0, i1 = unmasked_index_ranges(ma.getmask(y), compressed=False)
- # returns [[0,3,] [2,5,]]
+ #i0, i1 = unmasked_index_ranges(y.mask(), compressed=False)
+ i0, i1 = unmasked_index_ranges(ma.getmask(y), compressed=False)
+ # returns [[0,3,] [2,5,]]
- y.filled()[ii[1,0]:ii[1,1]]
- # returns np.array [3,4,]
-
+ y.filled()[ii[1,0]:ii[1,1]]
+ # returns np.array [3,4,]
'''
m = np.concatenate(((1,), mask, (1,)))
indices = np.arange(len(mask) + 1)
@@ -195,38 +195,11 @@
**kwargs
):
"""
- Create a Line2D instance with x and y data in sequences xdata,
- ydata
+ Create a :class:`~matplotlib.lines.Line2D` instance with *x*
+ and *y* data in sequences *xdata*, *ydata*.
The kwargs are Line2D properties:
- alpha: float
- animated: [True | False]
- antialiased or aa: [True | False]
- clip_box: a matplotlib.transform.Bbox instance
- clip_on: [True | False]
- color or c: any matplotlib color
- dash_capstyle: ['butt' | 'round' | 'projecting']
- dash_joinstyle: ['miter' | 'round' | 'bevel']
- dashes: sequence of on/off ink in points
- data: (np.array xdata, np.array ydata)
- figure: a matplotlib.figure.Figure instance
- label: any string
- linestyle or ls: [ '-' | '--' | '-.' | ':' | 'steps' | 'steps-pre' | 'steps-mid' | 'steps-post' | 'None' | ' ' | '' ]
- linewidth or lw: float value in points
- lod: [True | False]
- marker: [ '+' | ',' | '.' | '1' | '2' | '3' | '4' ]
- markeredgecolor or mec: any matplotlib color
- markeredgewidth or mew: float value in points (default 5)
- markerfacecolor or mfc: any matplotlib color
- markersize or ms: float
- pickradius: mouse event radius for pick items in points (default 5)
- solid_capstyle: ['butt' | 'round' | 'projecting']
- solid_joinstyle: ['miter' | 'round' | 'bevel']
- transform: a matplotlib.transform transformation instance
- visible: [True | False]
- xdata: np.array
- ydata: np.array
- zorder: any number
+ %(Line2D)s
"""
Artist.__init__(self)
@@ -290,12 +263,16 @@
self.set_data(xdata, ydata)
def contains(self, mouseevent):
- """Test whether the mouse event occurred on the line. The pick radius determines
- the precision of the location test (usually within five points of the value). Use
- get/set pickradius() to view or modify it.
+ """
+ Test whether the mouse event occurred on the line. The pick
+ radius determines the precision of the location test (usually
+ within five points of the value). Use
+ :meth:`~matplotlib.lines.Line2D.get_pickradius`/:meth:`~matplotlib.lines.Line2D.set_pickradius`
+ to view or modify it.
- Returns True if any values are within the radius along with {'ind': pointlist},
- np.where pointlist is the set of points within the radius.
+ Returns *True* if any values are within the radius along with
+ ``{'ind': pointlist}``, where *pointlist* is the set of points
+ within the radius.
TODO: sort returned indices by distance
"""
@@ -530,14 +507,20 @@
def get_markersize(self): return self._markersize
def get_data(self, orig=True):
- 'return the xdata, ydata; if orig is True, return the original data'
+ """
+ Return the xdata, ydata.
+
+ If *orig* is *True*, return the original data
+ """
return self.get_xdata(orig=orig), self.get_ydata(orig=orig)
def get_xdata(self, orig=True):
"""
- return the xdata; if orig is true return the original data,
- else the processed data
+ Return the xdata.
+
+ If *orig* is *True*, return the original data, else the
+ processed data.
"""
if orig:
return self._xorig
@@ -547,8 +530,10 @@
def get_ydata(self, orig=True):
"""
- return the ydata; if orig is true return the original data,
- else the processed data
+ Return the ydata.
+
+ If *orig* is *True*, return the original data, else the
+ processed data.
"""
if orig:
return self._yorig
@@ -558,13 +543,17 @@
def get_path(self):
"""
- Return the Path object associated with this line.
+ Return the :class:`~matplotlib.path.Path` object associated
+ with this line.
"""
if self._invalid:
self.recache()
return self._path
def get_xydata(self):
+ """
+ Return the *xy* data as a Nx2 numpy array.
+ """
if self._invalid:
self.recache()
return self._xy
@@ -1140,6 +1129,7 @@
def set_dash_capstyle(self, s):
"""
Set the cap style for dashed linestyles
+
ACCEPTS: ['butt' | 'round' | 'projecting']
"""
s = s.lower()
@@ -1153,6 +1143,7 @@
def set_solid_capstyle(self, s):
"""
Set the cap style for solid linestyles
+
ACCEPTS: ['butt' | 'round' | 'projecting']
"""
s = s.lower()
@@ -1183,9 +1174,10 @@
class VertexSelector:
"""
- manage the callbacks to maintain a list of selected vertices for
- matplotlib.lines.Line2D. Derived classes should override
- process_selected to do something with the picks
+ Manage the callbacks to maintain a list of selected vertices for
+ :class:`matplotlib.lines.Line2D`. Derived classes should override
+ :meth:`~matplotlib.lines.VertexSelector.process_selected` to do
+ something with the picks.
Here is an example which highlights the selected verts with red
circles::
@@ -1214,9 +1206,10 @@
"""
def __init__(self, line):
"""
- Initialize the class with a matplotlib.lines.Line2D instance.
- The line should already be added to some matplotlib.axes.Axes
- instance and should have the picker property set.
+ Initialize the class with a :class:`matplotlib.lines.Line2D`
+ instance. The line should already be added to some
+ :class:`matplotlib.axes.Axes` instance and should have the
+ picker property set.
"""
if not hasattr(line, 'axes'):
raise RuntimeError('You must first add the line to the Axes')
@@ -1234,15 +1227,16 @@
def process_selected(self, ind, xs, ys):
"""
- Default do nothing implementation of the process_selected method.
+ Default "do nothing" implementation of the
+ :meth:`process_selected` method.
- ind are the indices of the selected vertices. xs and ys are
- the coordinates of the selected vertices.
+ *ind* are the indices of the selected vertices. *xs* and *ys*
+ are the coordinates of the selected vertices.
"""
pass
def onpick(self, event):
- 'when the line is picked, update the set of selected indicies'
+ 'When the line is picked, update the set of selected indicies.'
if event.artist is not self.line: return
for i in event.ind:
@@ -1261,3 +1255,7 @@
lineMarkers = Line2D._markers
artist.kwdocd['Line2D'] = artist.kwdoc(Line2D)
+
+# You can not set the docstring of an instancemethod,
+# but you can on the underlying function. Go figure.
+Line2D.__init__.im_func.__doc__ = dedent(Line2D.__init__.__doc__) % artist.kwdocd
Modified: trunk/matplotlib/lib/matplotlib/patches.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/patches.py 2008-06-20 18:43:08 UTC (rev 5621)
+++ trunk/matplotlib/lib/matplotlib/patches.py 2008-06-20 19:46:05 UTC (rev 5622)
@@ -1,3 +1,5 @@
+# -*- coding: utf-8 -*-
+
from __future__ import division
import math
@@ -40,11 +42,10 @@
class Patch(artist.Artist):
"""
- A patch is a 2D thingy with a face color and an edge color
+ A patch is a 2D thingy with a face color and an edge color.
- If any of edgecolor, facecolor, linewidth, or antialiased are
- None, they default to their rc params setting
-
+ If any of *edgecolor*, *facecolor*, *linewidth*, or *antialiased*
+ are *None*, they default to their rc params setting.
"""
zorder = 1
def __str__(self):
@@ -82,9 +83,9 @@
def get_verts(self):
"""
- return a copy of the vertices used in this patch
+ Return a copy of the vertices used in this patch
- If the patch contains Bezier curves, the curves will be
+ If the patch contains Bézier curves, the curves will be
interpolated by line segments. To access the curves as
curves, use :meth:`get_path`.
"""
@@ -205,23 +206,24 @@
"""
Set the hatching pattern
- hatch can be one of:
- / - diagonal hatching
- \ - back diagonal
- | - vertical
- - - horizontal
- # - crossed
- x - crossed diagonal
- letters can be combined, in which case all the specified
- hatchings are done
- if same letter repeats, it increases the density of hatching
- in that direction
+ hatch can be one of::
+ / - diagonal hatching
+ \ - back diagonal
+ | - vertical
+ - - horizontal
+ # - crossed
+ x - crossed diagonal
+
+ Letters can be combined, in which case all the specified
+ hatchings are done. If same letter repeats, it increases the
+ density of hatching in that direction.
+
CURRENT LIMITATIONS:
- 1. Hatching is supported in the PostScript
- backend only.
- 2. Hatching is done with solid black lines of width 0.
+ 1. Hatching is supported in the PostScript backend only.
+
+ 2. Hatching is done with solid black lines of width 0.
"""
self._hatch = h
@@ -280,9 +282,10 @@
def __init__(self, patch, ox, oy, props=None, **kwargs):
"""
- Create a shadow of the patch offset by ox, oy. props, if not None is
- a patch property update dictionary. If None, the shadow will have
- have the same color as the face, but darkened
+ Create a shadow of the given *patch* offset by *ox*, *oy*.
+ *props*, if not *None*, is a patch property update dictionary.
+ If *None*, the shadow will have have the same color as the face,
+ but darkened.
kwargs are
%(Patch)s
@@ -332,9 +335,8 @@
class Rectangle(Patch):
"""
- Draw a rectangle with lower left at xy=(x,y) with specified
+ Draw a rectangle with lower left at *xy*=(*x*, *y*) with specified
width and height
-
"""
def __str__(self):
@@ -343,12 +345,8 @@
def __init__(self, xy, width, height, **kwargs):
"""
- xy is an x,y tuple lower, left
+ *fill* is a boolean indicating whether to fill the rectangle
- width and height are width and height of rectangle
-
- fill is a boolean indicating whether to fill the rectangle
-
Valid kwargs are:
%(Patch)s
"""
@@ -462,11 +460,18 @@
def __init__(self, xy, numVertices, radius=5, orientation=0,
**kwargs):
"""
- xy is a length 2 tuple (the center)
- numVertices is the number of vertices.
- radius is the distance from the center to each of the vertices.
- orientation is in radians and rotates the polygon.
+ *xy*
+ A length 2 tuple (*x*, *y*) of the center.
+ *numVertices*
+ the number of vertices.
+
+ *radius*
+ The distance from the center to each of the vertices.
+
+ *orientation*
+ rotates the polygon (in radians).
+
Valid kwargs are:
%(Patch)s
"""
@@ -528,7 +533,7 @@
def __init__(self, path, **kwargs):
"""
- path is a Path object
+ *path* is a :class:`matplotlib.path.Path` object.
Valid kwargs are:
%(Patch)s
@@ -550,8 +555,11 @@
def __init__(self, xy, closed=True, **kwargs):
"""
- xy is a numpy array with shape Nx2
+ *xy* is a numpy array with shape Nx2.
+ If *closed* is *True*, the polygon will be closed so the
+ starting and ending points are the same.
+
Valid kwargs are:
%(Patch)s
See Patch documentation for additional kwargs
@@ -580,23 +588,30 @@
xy = xy[0:-1]
self._set_xy(xy)
- def _get_xy(self):
+ def get_xy(self):
return self._path.vertices
- def _set_xy(self, vertices):
+ def set_xy(self, vertices):
self._path = Path(vertices)
- xy = property(_get_xy, _set_xy)
+ xy = property(
+ get_xy, set_xy, None,
+ """Set/get the vertices of the polygon. This property is
+ provided for backward compatibility with matplotlib 0.91.x
+ only. New code should use
+ :meth:`~matplotlib.patches.Polygon.get_xy` and
+ :meth:`~matplotlib.patches.Polygon.set_xy` instead.""")
class Wedge(Patch):
def __str__(self):
return "Wedge(%g,%g)"%self.xy[0]
+
def __init__(self, center, r, theta1, theta2, **kwargs):
"""
- Draw a wedge centered at x,y tuple center with radius r that
- sweeps theta1 to theta2 (angles)
+ Draw a wedge centered at *x*, *y* center with radius *r* that
+ sweeps *theta1* to *theta2* (in degrees).
Valid kwargs are:
+
%(Patch)s
-
"""
Patch.__init__(self, **kwargs)
self.center = center
@@ -621,7 +636,7 @@
# COVERAGE NOTE: Not used internally or from examples
class Arrow(Patch):
"""
- An arrow patch
+ An arrow patch.
"""
def __str__(self):
return "Arrow()"
@@ -633,8 +648,9 @@
[ 0.8, 0.1 ], [ 0.0, 0.1] ] )
def __init__( self, x, y, dx, dy, width=1.0, **kwargs ):
- """Draws an arrow, starting at (x,y), direction and length
- given by (dx,dy) the width of the arrow is scaled by width
+ """
+ Draws an arrow, starting at (*x*, *y*), direction and length
+ given by (*dx*, *dy*) the width of the arrow is scaled by *width*.
Valid kwargs are:
%(Patch)s
@@ -658,7 +674,9 @@
return self._patch_transform
class FancyArrow(Polygon):
- """Like Arrow, but lets you set head width and head height independently."""
+ """
+ Like Arrow, but lets you set head width and head height independently.
+ """
def __str__(self):
return "FancyArrow()"
@@ -666,18 +684,20 @@
def __init__(self, x, y, dx, dy, width=0.001, length_includes_head=False, \
head_width=None, head_length=None, shape='full', overhang=0, \
head_starts_at_zero=False,**kwargs):
- """Returns a new Arrow.
+ """
+ *length_includes_head*:
+ *True* if head is counted in calculating the length.
- length_includes_head: True if head is counted in calculating the length.
+ *shape*: ['full', 'left', 'right']
- shape: ['full', 'left', 'right']
+ *overhang*:
+ distance that the arrow is swept back (0 overhang means
+ triangular shape).
- overhang: distance that the arrow is swept back (0 overhang means
- triangular shape).
+ *head_starts_at_zero*:
+ If *True*, the head starts being drawn at coordinate 0
+ instead of ending at coordinate 0.
- head_starts_at_zero: if True, the head starts being drawn at coordinate
- 0 instead of ending at coordinate 0.
-
Valid kwargs are:
%(Patch)s
@@ -731,23 +751,35 @@
class YAArrow(Patch):
"""
- Yet another arrow class
+ Yet another arrow class.
This is an arrow that is defined in display space and has a tip at
- x1,y1 and a base at x2, y2.
+ *x1*, *y1* and a base at *x2*, *y2*.
"""
def __str__(self):
return "YAArrow()"
def __init__(self, figure, xytip, xybase, width=4, frac=0.1, headwidth=12, **kwargs):
"""
- xytip : (x,y) location of arrow tip
- xybase : (x,y) location the arrow base mid point
- figure : the figure instance (fig.dpi)
- width : the width of the arrow in points
- frac : the fraction of the arrow length occupied by the head
- headwidth : the width of the base of the arrow head in points
+ *xytip*
+ (*x*, *y*) location of arrow tip
+ *xybase*
+ (*x*, *y*) location the arrow base mid point
+
+ *figure*
+ The :class:`~matplotlib.figure.Figure` instance
+ (fig.dpi)
+
+ *width*
+ The width of the arrow in points
+
+ *frac*
+ The fraction of the arrow length occupied by the head
+
+ *headwidth*
+ The width of the base of the arrow head in points
+
Valid kwargs are:
%(Patch)s
@@ -790,9 +822,10 @@
def getpoints(self, x1,y1,x2,y2, k):
"""
- for line segment defined by x1,y1 and x2,y2, return the points on
- the line that is perpendicular to the line and intersects x2,y2
- and the distance from x2,y2 ot the returned points is k
+ For line segment defined by (*x1*, *y1*) and (*x2*, *y2*)
+ return the points on the line that is perpendicular to the
+ line and intersects (*x2*, *y2*) and the distance from (*x2*,
+ *y2*) of the returned points is *k*.
"""
x1,y1,x2,y2,k = map(float, (x1,y1,x2,y2,k))
m = (y2-y1)/(x2-x1)
@@ -811,7 +844,7 @@
class CirclePolygon(RegularPolygon):
"""
- A circle patch
+ A polygon-approximation of a circle patch.
"""
def __str__(self):
return "CirclePolygon(%d,%d)"%self.center
@@ -820,7 +853,10 @@
resolution=20, # the number of vertices
**kwargs):
"""
- Create a circle at xy=(x,y) with radius given by 'radius'
+ Create a circle at *xy* = (*x*, *y*) with given *radius*.
+ This circle is approximated by a regular polygon with
+ *resolution* sides. For a smoother circle drawn with splines,
+ see :class:`~matplotlib.patches.Circle`.
Valid kwargs are:
%(Patch)s
@@ -836,18 +872,25 @@
class Ellipse(Patch):
"""
- A scale-free ellipse
+ A scale-free ellipse.
"""
def __str__(self):
return "Ellipse(%s,%s;%sx%s)"%(self.center[0],self.center[1],self.width,self.height)
def __init__(self, xy, width, height, angle=0.0, **kwargs):
"""
- xy - center of ellipse
- width - length of horizontal axis
- height - length of vertical axis
- angle - rotation in degrees (anti-clockwise)
+ *xy*
+ center of ellipse
+ *width*
+ length of horizontal axis
+
+ *height*
+ length of vertical axis
+
+ *angle*
+ rotation in degrees (anti-clockwise)
+
Valid kwargs are:
%(Patch)s
"""
@@ -888,16 +931,17 @@
class Circle(Ellipse):
"""
- A circle patch
+ A circle patch.
"""
def __str__(self):
return "Circle((%g,%g),r=%g)"%(self.center[0],self.center[1],self.radius)
def __init__(self, xy, radius=5, **kwargs):
"""
- Create true circle at center xy=(x,y) with given radius;
- unlike circle polygon which is a polygonal approcimation, this
- uses splines and is much closer to a scale free circle
+ Create true circle at center *xy* = (*x*, *y*) with given
+ *radius*. Unlike :class:`~matplotlib.patches.CirclePolygon`
+ which is a polygonal approximation, this uses Bézier splines
+ and is much closer to a scale-free circle.
Valid kwargs are:
%(Patch)s
@@ -917,27 +961,40 @@
An elliptical arc. Because it performs various optimizations, it
can not be filled.
- The arc must be used in an Axes instance it cannot be added
- directly to a Figure) because it is optimized to only render the
- segments that are inside the axes bounding box with high
- resolution.
+ The arc must be used in an :class:`~matplotlib.axes.Axes`
+ instance---it cannot be added directly to a
+ :class:`~matplotlib.figure.Figure`---because it is optimized to
+ only render the segments that are inside the axes bounding box
+ with high resolution.
"""
def __str__(self):
return "Arc(%s,%s;%sx%s)"%(self.center[0],self.center[1],self.width,self.height)
def __init__(self, xy, width, height, angle=0.0, theta1=0.0, theta2=360.0, **kwargs):
"""
- xy - center of ellipse
- width - length of horizontal axis
- height - length of vertical axis
- angle - rotation in degrees (anti-clockwise)
- theta1 - starting angle of the arc in degrees
- theta2 - ending angle of the arc in degrees
+ *xy*
+ center of ellipse
- If theta1 and theta2 are not provided, the arc will form a
+ *width*
+ length of horizontal axis
+
+ *height*
+ length of vertical axis
+
+ *angle*
+ rotation in degrees (anti-clockwise)
+
+ *theta1*
+ starting angle of the arc in degrees
+
+ *theta2*
+ ending angle of the arc in degrees
+
+ If *theta1* and *theta2* are not provided, the arc will form a
complete ellipse.
Valid kwargs are:
+
%(Patch)s
"""
fill = kwargs.pop('fill')
@@ -974,24 +1031,26 @@
(8). The algorithm proceeds as follows:
1. The points where the ellipse intersects the axes bounding
- box are located. (This is done be performing an inverse
- transformation on the axes bbox such that it is relative to
- the unit circle -- this makes the intersection calculation
- much easier than doing rotated ellipse intersection
- directly).
+ box are located. (This is done be performing an inverse
+ transformation on the axes bbox such that it is relative
+ to the unit circle -- this makes the intersection
+ calculation much easier than doing rotated ellipse
+ intersection directly).
- This uses the "line intersecting a circle" algorithm from:
+ This uses the "line intersecting a circle" algorithm
+ from:
- Vince, John. Geometry for Computer Graphics: Formulae,
- Examples & Proofs. London: Springer-Verlag, 2005.
+ Vince, John. Geometry for Computer Graphics: Formulae,
+ Examples & Proofs. London: Springer-Verlag, 2005.
2. The angles of each of the intersection points are
- calculated.
+ calculated.
3. Proceeding counterclockwise starting in the positive
- x-direction, each of the visible arc-segments between the
- pairs of vertices are drawn using the bezier arc
- approximation technique implemented in Path.arc().
+ x-direction, each of the visible arc-segments between the
+ pairs of vertices are drawn using the bezier arc
+ approximation technique implemented in
+ :meth:`matplotlib.path.Path.arc`.
"""
if not hasattr(self, 'axes'):
raise RuntimeError('Arcs can only be used in Axes instances')
@@ -1100,11 +1159,12 @@
def bbox_artist(artist, renderer, props=None, fill=True):
"""
This is a debug function to draw a rectangle around the bounding
- box returned by get_window_extent of an artist, to test whether
- the artist is returning the correct bbox
+ box returned by
+ :meth:`~matplotlib.artist.Artist.get_window_extent` of an artist,
+ to test whether the artist is returning the correct bbox.
- props is a dict of rectangle props with the additional property
- 'pad' that sets the padding around the bbox in points
+ *props* is a dict of rectangle props with the additional property
+ 'pad' that sets the padding around the bbox in points.
"""
if props is None: props = {}
props = props.copy() # don't want to alter the pad externally
@@ -1130,8 +1190,9 @@
def draw_bbox(bbox, renderer, color='k', trans=None):
"""
This is a debug function to draw a rectangle around the bounding
- box returned by get_window_extent of an artist, to test whether
- the artist is returning the correct bbox
+ box returned by
+ :meth:`~matplotlib.artist.Artist.get_window_extent` of an artist,
+ to test whether the artist is returning the correct bbox.
"""
l,b,w,h = bbox.get_bounds()
@@ -1147,5 +1208,5 @@
artist.kwdocd['Patch'] = patchdoc = artist.kwdoc(Patch)
for k in ('Rectangle', 'Circle', 'RegularPolygon', 'Polygon', 'Wedge', 'Arrow',
- 'FancyArrow', 'YAArrow', 'CirclePolygon', 'Ellipse'):
+ 'FancyArrow', 'YAArrow', 'CirclePolygon', 'Ellipse', 'Arc'):
artist.kwdocd[k] = patchdoc
Modified: trunk/matplotlib/lib/matplotlib/text.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/text.py 2008-06-20 18:43:08 UTC (rev 5621)
+++ trunk/matplotlib/lib/matplotlib/text.py 2008-06-20 19:46:05 UTC (rev 5622)
@@ -97,7 +97,8 @@
**kwargs
):
"""
- Create a Text instance at x,y with string text.
+ Create a :class:`~matplotlib.text.Text` instance at *x*, *y*
+ with string *text*.
Valid kwargs are
%(Text)s
@@ -648,50 +649,51 @@
class TextWithDash(Text):
"""
- This is basically a Text with a dash (drawn with a Line2D)
- before/after it. It is intended to be a drop-in replacement
- for Text, and should behave identically to Text when
- dashlength=0.0.
+ This is basically a :class:`~matplotlib.text.Text` with a dash
+ (drawn with a :class:`~matplotlib.lines.Line2D`) before/after
+ it. It is intended to be a drop-in replacement for
+ :class:`~matplotlib.text.Text`, and should behave identically to
+ it when *dashlength* = 0.0.
The dash always comes between the point specified by
- set_position() and the text. When a dash exists, the
- text alignment arguments (horizontalalignment,
- verticalalignment) are ignored.
+ :meth:`~matplotlib.text.Text.set_position` and the text. When a
+ dash exists, the text alignment arguments (*horizontalalignment*,
+ *verticalalignment*) are ignored.
- dashlength is the length of the dash in canvas units.
- (default=0.0).
+ *dashlength* is the length of the dash in canvas units.
+ (default = 0.0).
- dashdirection is one of 0 or 1, np.where 0 draws the dash
- after the text and 1 before.
- (default=0).
+ *dashdirection* is one of 0 or 1, where 0 draws the dash after the
+ text and 1 before. (default = 0).
- dashrotation specifies the rotation of the dash, and
- should generally stay None. In this case
- self.get_dashrotation() returns self.get_rotation().
- (I.e., the dash takes its rotation from the text's
- rotation). Because the text center is projected onto
- the dash, major deviations in the rotation cause
+ *dashrotation* specifies the rotation of the dash, and should
+ generally stay *None*. In this case
+ :meth:`~matplotlib.text.TextWithDash.get_dashrotation` returns
+ :meth:`~matplotlib.text.Text.get_rotation`. (I.e., the dash takes
+ its rotation from the text's rotation). Because the text center is
+ projected onto the dash, major deviations in the rotation cause
what may be considered visually unappealing results.
- (default=None).
+ (default = *None*)
- dashpad is a padding length to add (or subtract) space
+ *dashpad* is a padding length to add (or subtract) space
between the text and the dash, in canvas units.
- (default=3).
+ (default = 3)
- dashpush "pushes" the dash and text away from the point
- specified by set_position() by the amount in canvas units.
- (default=0)
+ *dashpush* "pushes" the dash and text away from the point
+ specified by :meth:`~matplotlib.text.Text.set_position` by the
+ amount in canvas units. (default = 0)
- NOTE: The alignment of the two objects is based on the
- bbox of the Text, as obtained by get_window_extent().
- This, in turn, appears to depend on the font metrics
- as given by the rendering backend. Hence the quality
- of the "centering" of the label text with respect to
- the dash varies depending on the backend used.
+ *NOTE*: The alignment of the two objects is based on the bounding
+ box of the :class:`~matplotlib.text.Text`, as obtained by
+ :meth:`~matplotlib.artist.Artist.get_window_extent`. This, in
+ turn, appears to depend on the font metrics as given by the
+ rendering backend. Hence the quality of the "centering" of the
+ label text with respect to the dash varies depending on the
+ backend used.
- NOTE2: I'm not sure that I got the get_window_extent()
- right, or whether that's sufficient for providing the
- object bbox.
+ *NOTE 2*: I'm not sure that I got the
+ :meth:`~matplotlib.text.TextWithDash.get_window_extent` right, or
+ whether that's sufficient for providing the object bounding box.
"""
__name__ = 'textwithdash'
@@ -749,11 +751,11 @@
def get_prop_tup(self):
"""
- Return a hashable tuple of properties
+ Return a hashable tuple of properties.
Not intended to be human readable, but useful for backends who
want to cache derived information about text (eg layouts) and
- need to know if the text has changed
+ need to know if the text has changed.
"""
props = [p for p in Text.get_prop_tup(self)]
props.extend([self._x, self._y, self._dashlength, self._dashdirection, self._dashrotation, self._dashpad, self._dashpush])
@@ -973,8 +975,10 @@
class Annotation(Text):
"""
- A Text class to make annotating things in the figure: Figure,
- Axes, Point, Rectangle, etc... easier
+ A :class:`~matplotlib.text.Text` class to make annotating things
+ in the figure, such as :class:`~matplotlib.figure.Figure`,
+ :class:`~matplotlib.axes.Axes`,
+ :class:`~matplotlib.patches.Rectangle`, etc., easier.
"""
def __str__(self):
return "Annotation(%g,%g,%s)"%(self.xy[0],self.xy[1],self._text)
@@ -985,9 +989,9 @@
arrowprops=None,
**kwargs):
"""
- Annotate the *x*, *y* point *xy* with text *s* at *x*, *y* location *xytext*.
- (If *xytext* = *None*, defaults to *xy*, and if *textcoords* = *None*, defaults
- to *xycoords*).
+ Annotate the *x*, *y* point *xy* with text *s* at *x*, *y*
+ location *xytext*. (If *xytext* = *None*, defaults to *xy*,
+ and if *textcoords* = *None*, defaults to *xycoords*).
*arrowprops*, if not *None*, is a dictionary of line properties
(see :class:`matplotlib.lines.Line2D`) for the arrow that connects
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|