Python API

Tables

class RPA.Tables.Table(data=None, columns=None, index=None)

Bases: object

Container class for tabular data.

Supported data formats:

  • empty: None values populated according to columns/index

  • list: List of objects that contain values, which themselves can be namedtuples, dictionaries, lists, or tuples

  • dict: Dictionary of columns as keys and rows as values

Todo

Distinguish between range-based index and named index

Todo

Integers as column names? Columns forced to strings?

Todo

Implement column slicing

Todo

Index accessing through dot notation?

Todo

Index name conflict in exports/imports

Todo

Return Robot Framework DotDict instead of dict?

Parameters

  • data – values for table, see “Supported data formats”

  • columns – names for columns, should match data dimensions

  • index – names for rows, should match data dimensions

append_column(column=None, values=None)
append_row(row=None, index=None)

Append new row to table.

append_rows(rows, indexes=None)

Append multiple rows to table.

append_table(table)

Append data from table to current data.

clear()

Remove all rows from this table.

column_location(value)
property columns
copy()

Create a copy of this table.

property data
delete_columns(columns)

Remove columns with matching names.

delete_rows(indexes)

Remove rows with matching indexes.

property dimensions
filter_by_column(column, condition)

Remove rows by evaluating condition for all column values. All rows where it evaluates to falsy are removed.

get(indexes=None, columns=None, as_list=False)

Get values from table. Return type depends on input dimensions.

If indexes and columns are scalar, i.e. not lists:

Returns single cell value

If either indexes or columns is a list:

Returns matching row or column

If both indexes and columns are lists:

Returns a new Table instance with matching cell values

Parameters

  • indexes – list of indexes, or all if not given

  • columns – list of columns, or all if not given

get_cell(index, column)

Get single cell value.

get_column(column, indexes=None, as_list=False)

Get row values from column.

Parameters

  • columns – name for column

  • indexes – row indexes to include, or all if not given

  • as_list – return column as dictionary, instead of list

get_row(index, columns=None, as_list=False)

Get column values from row.

Parameters

  • index – index for row

  • columns – column names to include, or all if not given

  • as_list – return row as dictionary, instead of list

get_slice(start=None, end=None)

Get a new table from rows between start and end index.

get_table(indexes=None, columns=None, as_list=False)

Get a new table from all cells matching indexes and columns.

group_by_column(column)

Group rows by column value and return as list of tables.

head(rows, as_list=False)

Return first n rows of table.

property index
index_location(value)
iter_dicts(with_index=True)

Iterate rows with values as dicts.

iter_lists(with_index=True)

Iterate rows with values as lists.

iter_tuples(with_index=True, name='Row')

Iterate rows with values as namedtuples. Converts column names to valid Python identifiers, e.g. “First Name” -> “First_Name”

reset_index(drop=False)

Remove all named row indexes and use range-based values.

set(indexes=None, columns=None, values=None)

Sets multiple cell values at a time.

Both indexes and columns can be scalar or list-like, which enables setting individual cells, rows/columns, or regions.

If values is scalar, all matching cells will be set to that value. Otherwise the length should match the cell count defined by the other parameters.

set_cell(index, column, value)

Set individual cell value. If either index or column is missing, they are created.

set_column(column, values)

Set values in column. If column is missing, it is created.

set_row(index, values)

Set values in row. If index is missing, it is created.

sort_by_column(columns, ascending=False)

Sort table by columns.

sort_by_index(ascending=False)

Sort table by index values.

tail(rows, as_list=False)

Return last n rows of table.

to_dict(with_index=True)

Convert table to dict representation.

to_list(with_index=True)

Convert table to list representation.

class RPA.Tables.Tables

Bases: object

Tables is a library for manipulating tabular data inside Robot Framework.

It can import data from various sources and apply different operations to it. Common use-cases are reading and writing CSV files, inspecting files in directories, or running tasks using existing Excel data.

Import types

The data from which a table can be created can be of two main types:

  1. An iterable of individual rows, like a list of lists, or list of dictionaries

  2. A dictionary of columns, where each dictionary value is a list of values

For instance, these two input values:

data1 = [
    {"name": "Mark", "age": 58},
    {"name": "John", "age": 22},
    {"name": "Adam", "age": 67},
]

data2 = {
    "name": ["Mark", "John", "Adam"],
    "age":  [    58,     22,     67],
}

Would both result in the following table:

Index

Name

Age

1

Mark

58

2

John

22

3

Adam

67

Examples

Robot Framework

The Tables library can load tabular data from various other libraries and manipulate it inside Robot Framework.

*** Settings ***
Library    RPA.Tables

*** Keywords ***
Files to Table
    ${files}=    List files in directory    ${CURDIR}
    ${files}=    Create table    ${files}
    Filter table by column    ${files}    size  >=  ${1024}
    FOR    ${file}    IN    @{files}
        Log    ${file}[name]
    END
    Write table to CSV    ${files}    ${OUTPUT_DIR}${/}files.csv

Python

The library is also available directly through Python, where it is easier to handle multiple different tables or do more bespoke manipulation operations.

from RPA.Tables import Tables

library = Tables()
orders = library.read_table_from_csv(
    "orders.csv", columns=["name", "mail", "product"]
)

customers = library.group_table_by_column(rows, "mail")
for customer in customers:
    for order in customer:
        add_cart(order)
    make_order()
ROBOT_LIBRARY_DOC_FORMAT = 'REST'
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
add_table_column(table, name=None, values=None)

Append a column to a table.

Parameters

  • table – table to modify

  • name – name of new column

  • values – row values (or single scalar value for all rows)

add_table_row(table, row, index=None)

Append rows to a table.

Parameters

  • table – table to modify

  • row – value for new row

  • index – index name for new row

clear_table(table)

Clear table in-place, but keep columns.

Parameters

table – table to clear

copy_table(table)

Copy table object.

Parameters

table – table to copy

create_table(data=None, trim=False, columns=None, index=None)

Create Table object from data.

Data can be a combination of various iterable containers, e.g. list of lists, list of dicts, dict of lists.

Parameters

  • data – source data for table

  • trim – remove all empty rows from the end of the worksheet, default False

  • columns – names of columns (optional)

  • index – names of rows (optional)

export_table(table, with_index=False, as_list=True)

Convert table object to standard Python containers.

Parameters

  • table – table to convert to dict

  • with_index – include index in values

  • as_list – export data as list instead of dict

filter_empty_rows(table)

Remove all rows from the table which have only None values.

Parameters

table – table to filter

filter_table_by_column(table, column, operator, value)

Return all rows where the column values match the given condition.

Parameters

  • table – table to filter

  • column – column to filter with

  • operator – filtering operator, e.g. >, <, ==, contains

  • value – value to compare column to (using operator)

find_table_rows(table, column, value, as_list=False)

Find a row in the table by a given column value.

Parameters

  • table – Table to find from

  • column – name of column to search

  • value – value to match for

  • as_list – return list instead of dictionary

get_table_cell(table, row, column)

Get a cell value from table.

Parameters

  • table – table to read from

  • row – row of cell

  • column – column of cell

get_table_column(table, column, as_list=False)

Get all column values from table.

Parameters

  • table – table to read

  • column – column to read

  • as_list – return list instead of dictionary

get_table_dimensions(table)

Return table dimensions, as (rows, columns).

Parameters

table – table to inspect

get_table_row(table, index, as_list=False)

Get a single row from table.

Parameters

  • table – table to read

  • row – row to read

  • as_list – return list instead of dictionary

get_table_slice(table, start=None, end=None)

Return a new Table from a subset of given Table rows.

Parameters

  • table – table to read from

  • start – start index (inclusive)

  • start – end index (inclusive)

group_table_by_column(table, column)

Group table by column and return a list of grouped Tables.

Parameters

  • table – table to use for grouping

  • column – column which is used as grouping criteria

merge_tables(*tables, index=None)

Create a union of two tables and their contents.

Parameters

  • tables – Tables to merge

  • index – Column name to use as index for merge

By default rows from all tables are appended one after the other. Optionally a column name can be given with index, which is used to merge rows together.

Example:

For instance, a name column could be used to identify unique rows and the merge operation should overwrite values instead of appending multiple copies of the same name.

Name

Price

Egg

10.0

Cheese

15.0

Ham

20.0

Name

Stock

Egg

12.0

Cheese

99.0

Ham

0.0

 
${products}=    Merge tables    ${prices}    ${stock}    index=Name
FOR    ${product}    IN    @{products}
    Log many
    ...    Product: ${product}[Name]
    ...    Price: ${product}[Price]
    ...    Stock: ${product}[Stock]
END
pop_table_column(table, column=None, as_list=False)

Remove column from table and return it.

Parameters

  • table – table to modify

  • column – column to remove

  • as_list – return list instead of dictionary

pop_table_row(table, index=None, as_list=False)

Remove row from table and return it.

Parameters

  • table – table to modify

  • index – row index, pops first row if none given

  • as_list – return list instead of dictionary

read_table_from_csv(path, header=None, columns=None, dialect=None, delimiters=None)

Read a CSV file as a table.

Parameters

  • path – path to CSV file

  • header – CSV file includes header

  • columns – names of columns in resulting table

  • dialect – format of CSV file

  • delimiters – string of possible delimiters

By default attempts to deduce the CSV format and headers from a sample of the input file. If it’s unable to determine the format automatically, the dialect and header will have to be defined manually.

Valid dialect values are excel, excel-tab, and unix, and header is boolean argument (True/False). Optionally a set of valid delimiters can be given as a string.

The columns argument can be used to override the names of columns in the resulting table. The amount of columns must match the input data.

rename_table_columns(table, columns, strict=False)

Renames columns in the Table with given values. Columns with name as None will be use previous value.

Parameters

  • table – table to modify

  • columns – list of new column names

  • strict – if True, raises ValueError if column lengths do not match

set_column_as_index(table, column=None)

Set existing column as index for rows.

Parameters

  • table – table to modify

  • column – column to convert to index

set_row_as_column_names(table, index)

Set existing row as names for columns.

Parameters

  • table – table to modify

  • index – row to use as column names

set_table_cell(table, row, column, value)

Set a cell value in the table.

Parameters

  • table – table to modify to

  • row – row of cell

  • column – column of cell

  • value – value to set

set_table_column(table, column, values)

Assign values to entire column in the table.

Parameters

  • table – table to modify

  • column – column to modify

  • values – value(s) to set

set_table_row(table, row, values)

Assign values to a row in the table.

Parameters

  • table – table to modify

  • row – row to modify

  • values – value(s) to set

sort_table_by_column(table, column, ascending=False)

Sort table in-place according to column.

Parameters

  • table – table to sort

  • column – column to sort with

  • ascending – table sort order

table_head(table, count=5, as_list=False)

Return first count rows from table.

Parameters

  • table – table to read from

  • count – number of lines to read

  • as_list – return list instead of Table

table_tail(table, count=5, as_list=False)

Return last count rows from table.

Parameters

  • table – table to read from

  • count – number of lines to read

  • as_list – return list instead of Table

trim_column_names(table)

Remove all extraneous whitespace from column names.

trim_empty_rows(table)

Remove all rows from the end of the table which have only None values.

Parameters

table – table to filter

write_table_to_csv(table, path, header=True, dialect='excel')

Write a table as a CSV file.

Parameters

  • path – path to write to

  • table – table to write

  • header – write columns as header to CSV file

  • dialect – the format of output CSV

Valid dialect values are excel, excel-tab, and unix.

RPA.Tables.if_none(value, default)

Return default if value is None.

RPA.Tables.to_identifier(val)

Convert string to valid identifier

RPA.Tables.to_list(obj, size=1)

Convert (possibly scalar) value to list of size.

RPA.Tables.uniq(seq)

Return list of unique values while preserving order. Values must be hashable.