10000 Improve table docs · matplotlib/matplotlib@73db1ff · GitHub
[go: up one dir, main page]
Skip to content

Commit 73db1ff

Browse files
timhoffmtimhoffm
committed
Improve table docs
1 parent 03b07fb commit 73db1ff

File tree

1 file changed

+59
-25
lines changed

1 file changed

+59
-25
lines changed

‎lib/matplotlib/table.py

Lines changed: 59 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,18 @@
11
"""
2-
Place a table below the x-axis at location loc.
2+
This module provides functionality to add a table to a plot.
33
4-
The table consists of a grid of cells.
4+
Use the factory function `~matplotlib.table.table` to create a ready-made
5+
table from texts. If you need more control, use the `.Table` class and its
6+
methods.
57
6-
The grid need not be rectangular and can have holes.
8+
The table consists of a grid of cells, which are indexed by (row, column).
9+
The cell (0, 0) is positioned at the top left.
710
8-
Cells are added by specifying their row and column.
9-
10-
For the purposes of positioning the cell at (0, 0) is
11-
assumed to be at the top left and the cell at (max_row, max_col)
12-
is assumed to be at bottom right.
13-
14-
8000 You can add additional cells outside this range to have convenient
15-
ways of positioning more interesting grids.
16-
17-
Author : John Gill <jng@europe.renre.com>
18-
Copyright : 2004 John Gill and John Hunter
19-
License : matplotlib license
11+
| Author : John Gill <jng@europe.renre.com>
12+
| Copyright : 2004 John Gill and John Hunter
13+
| License : matplotlib license
2014
15+
Thanks to John Gill for providing the class and table.
2116
"""
2217
import warnings
2318

@@ -31,9 +26,38 @@
3126

3227
class Cell(Rectangle):
3328
"""
34-
A cell is a `.Rectangle` with some associated text.
29+
A cell is a `.Rectangle` with some associated `.Text`.
30+
31+
.. note:
32+
As a user, you'll most likely not creates cells yourself. Instead, you
33+
should use either the `~matplotlib.table.table` factory function or
8000 34+
`.Table.add_cell`.
35+
36+
Parameters
37+
----------
38+
xy : 2-tuple
39+
The position of the bottom left corner of the cell.
40+
width : float
41+
The cell width.
42+
height : float
43+
The cell height.
44+
edgecolor : color spec
45+
The color of the cell border.
46+
facecolor : color spec
47+
The cell facecolor.
48+
fill : bool
49+
Whether the cell background is filled.
50+
text : str
51+
The cell text.
52+
loc : {'left', 'center', 'right'}, default: 'right'
53+
The alignment of the text within the cell.
54+
fontproperties : dict
55+
A dict defining the font properties of the text. Supported keys and
56+
values are the keyword arguments accepted by `.FontProperties`.
3557
"""
36-
PAD = 0.1 # padding between text and rectangle
58+
59+
PAD = 0.1
60+
"""Padding between text and rectangle."""
3761

3862
def __init__(self, xy, width, height,
3963
edgecolor='k', facecolor='w',
@@ -44,7 +68,7 @@ def __init__(self, xy, width, height,
4468
):
4569

4670
# Call base
47-
Rectangle.__init__(self, xy, width=width, height=height,
71+
Rectangle.__init__(self, xy, width=width, height=height, fill=fill,
4872
edgecolor=edgecolor, facecolor=facecolor)
4973
self.set_clip_on(False)
5074

@@ -70,6 +94,7 @@ def get_text(self):
7094
return self._text
7195

7296
def set_fontsize(self, size):
97+
"""Set the text fontsize."""
7398
self._text.set_fontsize(size)
7499
self.stale = True
75100

@@ -78,7 +103,7 @@ def get_fontsize(self):
78103
return self._text.get_fontsize()
79104

80105
def auto_set_font_size(self, renderer):
81-
""" Shrink font size until text fits. """
106+
"""Shrink font size until the text fits into the cell width."""
82107
fontsize = self.get_fontsize()
83108
required = self.get_required_width(renderer)
84109
while fontsize > 1 and required > self.get_width():
@@ -101,7 +126,7 @@ def draw(self, renderer):
101126
self.stale = False
102127

103128
def _set_text_position(self, renderer):
104-
""" Set text up so it draws in the right place.
129+
"""Set text up so it draws in the right place.
105130
106131
Currently support 'left', 'center' and 'right'
107132
"""
@@ -126,18 +151,27 @@ def _set_text_position(self, renderer):
126151
self._text.set_position((x, y))
127152

128153
def get_text_bounds(self, renderer):
129-
""" Get text bounds in axes co-ordinates. """
154+
"""
155+
Return the bounds of the text as *(x, y, width, height)* in table
156+
coordinates.
157+
"""
130158
bbox = self._text.get_window_extent(renderer)
131159
bboxa = bbox.inverse_transformed(self.get_data_transform())
132160
return bboxa.bounds
133161

134162
def get_required_width(self, renderer):
135-
""" Get width required for this cell. """
163+
"""Return the minimal required width for the cell."""
136164
l, b, w, h = self.get_text_bounds(renderer)
137165
return w * (1.0 + (2.0 * self.PAD))
138166

167+
@docstring.dedent_interpd
139168
def set_text_props(self, **kwargs):
140-
'update the text properties with kwargs'
169+
"""
170+
Update the text properties.
171+
172+
Valid kwargs are
173+
%(Text)s
174+
"""
141175
self._text.update(kwargs)
142176
self.stale = True
143177

@@ -211,6 +245,8 @@ class Table(Artist):
211245
212246
Column widths and row heights for the table can be specified.
213247
248+
The grid of cells can have holes.
249+
214250
Return value is a sequence of text, line and patch instances that make
215251
up the table
216252
"""
@@ -590,8 +626,6 @@ def table(ax,
590626
loc='bottom', bbox=None, edges='closed')
591627
592628
Factory function to generate a Table instance.
593-
594-
Thanks to John Gill for providing the class and table.
595629
"""
596630

597631
if cellColours is None and cellText is None:

0 commit comments

Comments
 (0)
0