Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 131f52b

Browse filesBrowse files
timhoffmtimhoffm
committed
More table documentation
1 parent 96522ff commit 131f52b
Copy full SHA for 131f52b

File tree

Expand file treeCollapse file tree

1 file changed

+159
-49
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+159
-49
lines changed

‎lib/matplotlib/table.py

Copy file name to clipboardExpand all lines: lib/matplotlib/table.py
+159-49Lines changed: 159 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ def set_text_props(self, **kwargs):
180180

181181
class CustomCell(Cell):
182182
"""
183-
A subclass of Cell where the sides may be visibly toggled.
183+
A `.Cell` subclass with configurable edge visibility.
184184
"""
185185

186186
_edges = 'BRTL'
@@ -196,6 +196,15 @@ def __init__(self, *args, visible_edges, **kwargs):
196196

197197
@property
198198
def visible_edges(self):
199+
"""
200+
The cell edges to be drawn with a line.
201+
202+
Reading this property returns a substring of 'BRTL' (bottom, right,
203+
top, left').
204+
205+
When setting this property, you can use a substring of 'BRTL' or one
206+
of {'open', 'closed', 'horizontal', 'vertical'}.
207+
"""
199208
return self._visible_edges
200209

201210
@visible_edges.setter
@@ -216,9 +225,7 @@ def visible_edges(self, value):
216225
self.stale = True
217226

218227
def get_path(self):
219-
"""
220-
Return a path where the edges specified by _visible_edges are drawn.
221-
"""
228+
"""Return a `.Path` for the `.visible_edges`."""
222229
codes = [Path.MOVETO]
223230

224231
for edge in self._edges:
@@ -239,13 +246,7 @@ def get_path(self):
239246

240247
class Table(Artist):
241248
"""
242-
Create a table of cells.
243-
244-
Table can have (optional) row and column headers.
245-
246-
Each entry in the table can be either text or patches.
247-
248-
Column widths and row heights for the table can be specified.
249+
A table of cells.
249250
250251
The table consists of a grid of cells, which are indexed by (row, column).
251252
@@ -255,8 +256,8 @@ class Table(Artist):
255256
You don't have to add a cell to every grid position, so you can create
256257
tables that have holes.
257258
258-
Return value is a sequence of text, line and patch instances that make
259-
up the table
259+
*Note*: You'll usually not create an empty table from scratch. Instead use
260+
`~matplotlib.table.table` to create a table from data.
260261
"""
261262
codes = {'best': 0,
262263
'upper right': 1, # default
@@ -277,11 +278,31 @@ class Table(Artist):
277278
'top': 16,
278279
'bottom': 17,
279280
}
281+
"""Possible values where to place the table relative to the Axes."""
280282

281283
FONTSIZE = 10
282-
AXESPAD = 0.02 # the border between the axes and table edge
284+
285+
AXESPAD = 0.02
286+
"""The border between the Axes and the table edge in Axes units."""
283287

284288
def __init__(self, ax, loc=None, bbox=None, **kwargs):
289+
"""
290+
Parameters
291+
----------
292+
ax : `matplotlib.axes.Axes`
293+
The `~.axes.Axes` to plot the table into.
294+
loc : str
295+
The position of the cell with respect to *ax*. This must be one of
296+
the `~.Table.codes`.
297+
bbox : `.Bbox` or None
298+
A bounding box to draw the table into. If this is not *None*, this
299+
overrides *loc*.
300+
301+
Other Parameters
302+
----------------
303+
**kwargs
304+
`.Artist` properties.
305+
"""
285306

286307
Artist.__init__(self)
287308

@@ -314,18 +335,21 @@ def __init__(self, ax, loc=None, bbox=None, **kwargs):
314335

315336
def add_cell(self, row, col, *args, **kwargs):
316337
"""
317-
Add a cell to the table.
338+
Create a cell and add it to the table.
318339
319340
Parameters
320341
----------
321342
row : int
322343
Row index.
323344
col : int
324345
Column index.
346+
*args, **kwargs
347+
All other parameters are passed on to `Cell`.
325348
326349
Returns
327350
-------
328-
`CustomCell`: Automatically created cell
351+
cell : `.CustomCell`
352+
The created cell.
329353
330354
"""
331355
xy = (0, 0)
@@ -361,6 +385,21 @@ def __getitem__(self, position):
361385

362386
@property
363387
def edges(self):
388+
"""
389+
The default value of `~.CustomCell.visible_edges` for newly added
390+
cells using `.add_cell`.
391+
392+
Notes
393+
-----
394+
This setting does currently only affect newly created cells using
395+
`.add_cell`.
396+
397+
To change existing cells, you have to set their edges explicitly::
398+
399+
for c in tab.get_celld().values():
400+
c.visible_edges = 'horizontal'
401+
402+
"""
364403
return self._edges
365404

366405
@edges.setter
@@ -374,6 +413,8 @@ def _approx_text_height(self):
374413

375414
@allow_rasterization
376415
def draw(self, renderer):
416+
# docstring inherited
417+
377418
# Need a renderer to do hit tests on mouseevent; assume the last one
378419
# will do
379420
if renderer is None:
@@ -403,10 +444,7 @@ def _get_grid_bbox(self, renderer):
403444
return bbox.inverse_transformed(self.get_transform())
404445

405446
def contains(self, mouseevent):
406-
"""Test whether the mouse event occurred in the table.
407-
408-
Returns T/F, {}
409-
"""
447+
# docstring inherited
410448
if callable(self._contains):
411449
return self._contains(self, mouseevent)
412450

@@ -466,26 +504,13 @@ def _do_cell_alignment(self):
466504
cell.set_y(bottoms[row])
467505

468506
def auto_set_column_width(self, col):
469-
""" Given column indexs in either List, Tuple or int. Will be able to
470-
automatically set the columns into optimal sizes.
471-
472-
Here is the example of the input, which triger automatic adjustment on
473-
columns to optimal size by given index numbers.
474-
-1: the row labling
475-
0: the 1st column
476-
1: the 2nd column
477-
478-
Args:
479-
col(List): list of indexs
480-
>>>table.auto_set_column_width([-1,0,1])
481-
482-
col(Tuple): tuple of indexs
483-
>>>table.auto_set_column_width((-1,0,1))
484-
485-
col(int): index integer
486-
>>>table.auto_set_column_width(-1)
487-
>>>table.auto_set_column_width(0)
488-
>>>table.auto_set_column_width(1)
507+
"""
508+
Automatically set the widths of given columns to optimal sizes.
509+
510+
Parameters
511+
----------
512+
col : int or sequence of ints
513+
The indices of the columns to auto-scale.
489514
"""
490515
# check for col possibility on iteration
491516
try:
@@ -536,7 +561,7 @@ def _auto_set_font_size(self, renderer):
536561
cell.set_fontsize(fontsize)
537562

538563
def scale(self, xscale, yscale):
539-
""" Scale column widths by xscale and row heights by yscale. """
564+
"""Scale column widths by *xscale* and row heights by *yscale*."""
540565
for c in self._cells.values():
541566
c.set_width(c.get_width() * xscale)
542567
c.set_height(c.get_height() * yscale)
@@ -548,8 +573,20 @@ def set_fontsize(self, size):
548573
Parameters
549574
----------
550575
size : float
551-
"""
552576
577+
Notes
578+
-----
579+
As long as auto font size has not been disabled, the value will be
580+
clipped such that the text fits horizontally into the cell.
581+
582+
You can disable this behavior using `.auto_set_font_size`.
583+
584+
>>> the_table.auto_set_font_size(False)
585+
>>> the_table.set_fontsize(20)
586+
587+
However, there is no automatic scaling of the row height so that the
588+
text may exceed the cell boundary.
589+
"""
553590
for cell in self._cells.values():
554591
cell.set_fontsize(size)
555592
self.stale = True
@@ -617,7 +654,18 @@ def _update_positions(self, renderer):
617654
self._offset(ox, oy)
618655

619656
def get_celld(self):
620-
"""Return a dict of cells in the table."""
657+
r"""
658+
Return a dict of cells in the table mapping *(row, column)* to
659+
`.Cell`\s.
660+
661+
Notes
662+
-----
663+
You can also directly index into the Table object to access individual
664+
cells::
665+
666+
cell = table[row, col]
667+
668+
"""
621669
return self._cells
622670

623671

@@ -629,13 +677,75 @@ def table(ax,
629677
loc='bottom', bbox=None, edges='closed',
630678
**kwargs):
631679
"""
632-
TABLE(cellText=None, cellColours=None,
633-
cellLoc='right', colWidths=None,
634-
rowLabels=None, rowColours=None, rowLoc='left',
635-
colLabels=None, colColours=None, colLoc='center',
636-
loc='bottom', bbox=None, edges='closed')
680+
Add a table to an `~.axes.Axes`.
681+
682+
At least one of *cellText* or *cellColours* must be specified. These
683+
parameters must be 2D lists, in which the outer lists define the rows and
684+
the inner list define the column values per row. Each row must have the
685+
same number of elements.
686+
687+
The table can optionally have row and column headers, which are configured
688+
using *rowLabels*, *rowColours*, *rowLoc* and *colLabels*, *colColours*,
689+
*colLoc* respectively.
690+
691+
Parameters
692+
----------
693+
cellText : 2D list of str, optional
694+
The texts to place into the table cells.
695+
696+
*Note*: Line breaks in the strings are currently not accounted for and
697+
will result in the text exceeding the cell boundaries.
698+
699+
cellColours : 2D list of matplotlib color specs, optional
700+
The background colors of the cells.
701+
702+
cellLoc : {'left', 'center', 'right'}, default: 'right'
703+
The alignment of the text within the cells.
704+
705+
colWidths : list of float, optional
706+
The column widths in units of the axes. If not given, all columns will
707+
have a width of *1 / ncols*.
708+
709+
rowLabels : list of str, optional
710+
The text of the row header cells.
711+
712+
rowColours : list of matplotlib color specs, optional
713+
The colors of the row header cells.
714+
715+
rowLoc : {'left', 'center', 'right'}, optional, default: 'left'
716+
The text alignment of the row header cells.
717+
718+
colLabels : list of str, optional
719+
The text of the column header cells.
720+
721+
colColours : list of matplotlib color specs, optional
722+
The colors of the column header cells.
723+
724+
rowLoc : {'left', 'center', 'right'}, optional, default: 'left'
725+
The text alignment of the column header cells.
726+
727+
loc : str, optional
728+
The position of the cell with respect to *ax*. This must be one of
729+
the `~.Table.codes`.
730+
731+
bbox : `.Bbox`, optional
732+
A bounding box to draw the table into. If this is not *None*, this
733+
overrides *loc*.
734+
735+
edges : substring of 'BRTL' or {'open', 'closed', 'horizontal', 'vertical'}
736+
The cell edges to be drawn with a line. See also
737+
`~.CustomCell.visible_edges`.
738+
739+
Other Parameters
740+
----------------
741+
**kwargs
742+
`.Artist` properties.
743+
744+
Returns
745+
-------
746+
table : `~matplotlib.table.Table`
747+
The created table.
637748
638-
Factory function to generate a Table instance.
639749
"""
640750

641751
if cellColours is None and cellText is None:

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.