Advanced Usage#

There are three types of Tablate container classes: Tablate, TablateSet and TablateItem. Each type have their own set of methods and also share common methods.

`Tablate` class#

The Tablate class is the most convenient of the three classes. It returns an empty Tablate container instance and allows the cumulative addition of frames using the add_text_frame(), add_grid_frame() and add_table_frame() methods. It also shares all of the TablateSet methods. The Tablate class requires no arguments but may take optional container and global default style arguments.

import tablate as tb

tab = tb.Tablate()

.add_text_frame() method

The add_text_frame() method adds a text frame to the Tablate container instance and requires one argument: the text (str, int, float) content for the text frame. It may also take optional style arguments.

tab.add_text_frame("Some text content...")

.add_grid_frame() method

The add_grid_frame() method adds a grid frame to the Tablate container instance and requires one argument: either a list of (str, int, float) or a list of column dicts. It may also take optional style arguments.

tab.add_grid_frame(["Column One", "Column Two", "Column Three"])

# or

tab.add_grid_frame([{"string": "Column One"}, {"string": "Column Two"}, {"string": "Column Three"}])

.add_table_frame() method

The add_table_frame() method adds a table frame to the Tablate container instance and requires two arguments: a list of column dicts and a list of row dicts. It may also take optional style arguments.

table_columns = [
    {
        "key": "col_one",
        "string": "Col One",
    },
    {
        "key": "col_two",
        "string": "Col One",
    },
    {
        "key": "col_three",
        "string": "Col One",
    }
]

table_rows = [
    {
        "col_one": "Column One, Row One",
        "col_two": "Column Two, Row One",
        "col_three": "Column Three, Row One"
    },
    {
        "col_one": "Column One, Row Two",
        "col_two": "Column Two, Row Two",
        "col_three": "Column Three, Row Two"
    },
    {
        "col_one": "Column One, Row Three",
        "col_two": "Column Two, Row Three",
        "col_three": "Column Three, Row Three"
    }
]

tab.add_table_frame(columns=table_columns, rows=table_rows)

.from_dict() method

The from_dict() method is intended to convert a Pandas DataFrame into a Tablate table frame (using the pandas.DataFrame.to_dict() method). It requires one arguments: a dataframe dict. It may also take optional style arguments.

dataframe_dict = {
    "one": [1, 2, 3],
    "two": [4, 5, 6]
}

tab.from_dict(dataframe_dict)

`TablateSet` class (and `concat` function)#

The TablateSet class is returned from the concat function. The concat function takes a list of Tablate, TablateSet or TablateItem instances and merges them into a single TablateSet container instance. A TablateSet instance is a Tablate container with one or more frames. The concat function may also take optional global style options.

tab_set = tb.concat([tab1, tab2, tab3])

The TablateSet class contains a set of methods for working with multiple frames:

.list_frames() method

The list_frames() method returns a list of the frames in the container instance with some details describing the frames. NOTE: The list_frames() method does not include all of the styling options.

tab.list_frames()

    │ Name                 │ Type   │ Cols. │  Rows │ Options [defaults]
 ───┼──────────────────────┼────────┼───────┼───────┼──────────────────────────────────────────
  0 │ UntitedTextFrame0    │ Text   │     - │     - │ [multiline]
  1 │ UntitedGridFrame0    │ Grid   │     3 │     - │ [multiline]
  2 │ UntitedTableFrame0   │ Table  │     3 │     0 │

.get_frame() method

The .get_frame() method selects a frame within a Tablate container instance (by name or index) and returns a TablateItem instance containing that frame.

tab_item = tab.get_frame("UntitedGridFrame0")

.remove_frame() method

The .remove_frame() method remove a frame within a Tablate container instance (by name or index).

tab.remove_frame(2)

.replace_frame() method

The .replace_frame() method selects a frame within a Tablate container instance (by name or index) and replaces it with another frame from a TablateItem instance (a Tablate or TablateSet can also be provided but the .replace() method will only take the first frame from either of these latter two).

tab.replace_frame(2, tab2)

.rename_frame() method

The .rename_frame() method selects a frame within a Tablate container instance (by name or index) and renames it.

tab.rename_frame(2, "Some new name")

`TablateItem` class (and `Text`, `Grid` and `Table` classes)#

The TablateItem class is returned from the Text, Grid and Table classes (as well as the get_frame() method on the Tablate or TablateSet classes). The Text, Grid and Table classes are primarily designed to be used in (but are not restricted to) an IPython environment (see IPython Usage for more information). A TablateItem class is a Tablate container with a simple frame.

The Text, Grid and Table classes take the same arguments as .add_text_frame(), .add_grid_frame() and .add_table_frame() methods on the Tablate class (with the addition of container styles.)

text_item = tb.Text(...)

grid_item = tb.Grid(...)

table_item = tb.Table(...)

The TablateItem class contains a set of methods for working with a single frame:

.name property

The name property is a getter/setter for the TablateItem name.

# getter
tab_item.name
# setter
tab_item.name = "new_name"

.rename() method

The .rename() method renames the TablateItem.

tab_item.rename("Some new name")

.to_dict() method

The to_dict() method returns the TablateItem as a dict which can be used to create a Pandas DataFrame.

tab_dict = tab_item.to_dict()
df = pandas.DataFrame(tab_dict)

Common Methods (`.apply()`, `.apply_style()`)#

.apply() method

The apply() method is a little tricky. It takes a function as an argument and iterates over each of the frames in the container instance, calling the function on each iteration. The function is passed four arguments: the frame name, the frame type, a dictionary of the argument used to construct the frame and the container (and possibly global default) styles. The function may return two items: a new dictionary for the frame and a new dictionary for the container (and possibly global default) styles. The Tablate container instance will attempt to merge these two return dicts with iterated frame. The .appy() method takes a an optional second argument to allow merge errors to be suppressed.

It is probably worth playing with to understand more clearly.

def some_func(frame_name, frame_type, frame_dict, global_dict):
    print(frame_name, frame_type, frame_dict, global_dict)

tab.apply(some_func)

.apply_style() method

The apply_style() method allows custom CSS styling to be applied to a Tablate container instance. The apply_style() method will use the specific randomised HTML wrapper classname to scope the style to the specific Tablate container instance. The apply_style() method requires two arguments: a CSS selector and a CSS string. The apply_style() method also accepts a third argument for a sub-selector. These styles will be placed in a block at the end of the HTML output to ensure that they override any existing styles.

tab.apply_style(".tablate_frame_0.tablate_column_2", "color:pink", " > p:hover")

Advanced Usage

Contents

Advanced Usage#

Tablate class#

TablateSet class (and concat function)#

TablateItem class (and Text, Grid and Table classes)#

Common Methods (.apply(), .apply_style())#

`Tablate` class#

`TablateSet` class (and `concat` function)#

`TablateItem` class (and `Text`, `Grid` and `Table` classes)#

Common Methods (`.apply()`, `.apply_style()`)#