Skip to content

Improve table docs #12218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 22, 2018
Merged

Improve table docs #12218

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 69 additions & 25 deletions lib/matplotlib/table.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
"""
Place a table below the x-axis at location loc.

The table consists of a grid of cells.
# Original code by:
# John Gill <jng@europe.renre.com>
# Copyright 2004 John Gill and John Hunter
#
# Subsequent changes:
# The Matplotlib development team
# Copyright The Matplotlib development team

The grid need not be rectangular and can have holes.

Cells are added by specifying their row and column.
"""
This module provides functionality to add a table to a plot.

For the purposes of positioning the cell at (0, 0) is
assumed to be at the top left and the cell at (max_row, max_col)
is assumed to be at bottom right.
Use the factory function `~matplotlib.table.table` to create a ready-made
table from texts. If you need more control, use the `.Table` class and its
methods.

You can add additional cells outside this range to have convenient
ways of positioning more interesting grids.
The table consists of a grid of cells, which are indexed by (row, column).
The cell (0, 0) is positioned at the top left.

Author : John Gill <jng@europe.renre.com>
Copyright : 2004 John Gill and John Hunter
License : matplotlib license
Thanks to John Gill for providing the class and table.
"""

from . import artist, cbook, docstring
Expand All @@ -29,9 +29,38 @@

class Cell(Rectangle):
"""
A cell is a `.Rectangle` with some associated text.
A cell is a `.Rectangle` with some associated `.Text`.

.. note:
As a user, you'll most likely not creates cells yourself. Instead, you
should use either the `~matplotlib.table.table` factory function or
`.Table.add_cell`.

Parameters
----------
xy : 2-tuple
The position of the bottom left corner of the cell.
width : float
The cell width.
height : float
The cell height.
edgecolor : color spec
The color of the cell border.
facecolor : color spec
The cell facecolor.
fill : bool
Whether the cell background is filled.
text : str
The cell text.
loc : {'left', 'center', 'right'}, default: 'right'
The alignment of the text within the cell.
fontproperties : dict
A dict defining the font properties of the text. Supported keys and
values are the keyword arguments accepted by `.FontProperties`.
"""
PAD = 0.1 # padding between text and rectangle

PAD = 0.1
"""Padding between text and rectangle."""
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kind of prefer leaving this as inline comment (fwiw).
(As a side note, compare with the padding of Annotations, which is also hardcoded

                    pad = renderer.points_to_pixels(4)

)

Copy link
Member Author

@timhoffm timhoffm Nov 2, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this is a public attribute, it shows up in the docs

I very much prefer that every element in the docs has a description. This is achived using the docstring

I would be fine not documenting PAD, but only if we also remove it from the docs (either by excluding explicitly (not sure if that's feasible with autodoc in this context), or preferably by renaming to _PAD.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I didn't realize sphinx would pick it up. I guess that works, then...


def __init__(self, xy, width, height,
edgecolor='k', facecolor='w',
Expand All @@ -42,7 +71,7 @@ def __init__(self, xy, width, height,
):

# Call base
Rectangle.__init__(self, xy, width=width, height=height,
Rectangle.__init__(self, xy, width=width, height=height, fill=fill,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess that's an intended new feature (respecting fill instead of dropping it)?.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. I assume that is was accidentally omitted. There's no point in having fill in __init__ if it's silently dropped.

edgecolor=edgecolor, facecolor=facecolor)
self.set_clip_on(False)

Expand All @@ -68,6 +97,7 @@ def get_text(self):
return self._text

def set_fontsize(self, size):
"""Set the text fontsize."""
self._text.set_fontsize(size)
self.stale = True

Expand All @@ -76,7 +106,7 @@ def get_fontsize(self):
return self._text.get_fontsize()

def auto_set_font_size(self, renderer):
""" Shrink font size until text fits. """
"""Shrink font size until the text fits into the cell width."""
fontsize = self.get_fontsize()
required = self.get_required_width(renderer)
while fontsize > 1 and required > self.get_width():
Expand All @@ -99,7 +129,7 @@ def draw(self, renderer):
self.stale = False

def _set_text_position(self, renderer):
""" Set text up so it draws in the right place.
"""Set text up so it draws in the right place.

Currently support 'left', 'center' and 'right'
"""
Expand All @@ -124,18 +154,26 @@ def _set_text_position(self, renderer):
self._text.set_position((x, y))

def get_text_bounds(self, renderer):
""" Get text bounds in axes co-ordinates. """
"""
Return the text bounds as *(x, y, width, height)* in table coordinates.
"""
bbox = self._text.get_window_extent(renderer)
bboxa = bbox.inverse_transformed(self.get_data_transform())
return bboxa.bounds

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

@docstring.dedent_interpd
def set_text_props(self, **kwargs):
'update the text properties with kwargs'
"""
Update the text properties.

Valid kwargs are
%(Text)s
"""
self._text.update(kwargs)
self.stale = True

Expand Down Expand Up @@ -209,6 +247,14 @@ class Table(Artist):

Column widths and row heights for the table can be specified.

The table consists of a grid of cells, which are indexed by (row, column).

For a simple table, you'll have a full grid of cells with indices from
(0, 0) to (num_rows-1, num_cols-1), in which the cell (0, 0) is positioned
at the top left. However, you can also add cells with negative indices.
You don't have to add a cell to every grid position, so you can create
tables that have holes.

Return value is a sequence of text, line and patch instances that make
up the table
"""
Expand Down Expand Up @@ -590,8 +636,6 @@ def table(ax,
loc='bottom', bbox=None, edges='closed')

Factory function to generate a Table instance.

Thanks to John Gill for providing the class and table.
"""

if cellColours is None and cellText is None:
Expand Down