Python API

Tables

class RPA.Tables.Dialect(value)

Bases: Enum

CSV dialect

Excel = 'excel'
ExcelTab = 'excel-tab'
Unix = 'unix'
class RPA.Tables.Table(data: Optional[Union[Dict[Union[int, str], Union[Dict, List, Tuple, NamedTuple, set]], List[Union[Dict, List, Tuple, NamedTuple, set]], Table]] = None, columns: Optional[List[str]] = None)

Bases: object

Container class for tabular data.

Supported data formats:

  • empty: None values populated according to columns/index

  • list: list of data Rows

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

  • table: An existing Table

Row: a namedtuple, dictionary, list or a tuple

Parameters

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

  • columns – Names for columns, should match data dimensions

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

Append new row to table.

append_rows(rows)

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)

Find location for column value.

property columns
copy()

Create a copy of this table.

property data
delete_columns(columns)

Remove columns with matching names.

delete_rows(indexes: Union[int, str, List[Union[int, str]]])

Remove rows with matching indexes.

property dimensions
filter_all(condition: Callable[[Union[int, str, Dict, List, Tuple, NamedTuple, set]], bool])

Remove rows by evaluating condition for every row.

The filtering will be done in-place and all the rows evaluating as falsy through the provided condition will be removed.

filter_by_column(column: Union[int, str], condition: Callable[[Any], bool])

Remove rows by evaluating condition for cells in column.

The filtering will be done in-place and all the 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: Union[int, str], 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: Optional[Union[int, str]] = None, end: Optional[Union[int, str]] = 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: Union[int, str]) → int
iter_dicts(with_index=True) → Generator[Dict[Union[int, str], Any], None, None]

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”

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.

property size: int
sort_by_column(columns, ascending=False)

Sort table by columns.

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 a table can be created from 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

0

Mark

58

1

John

22

2

Adam

67

Indexing columns and rows

Columns can be referred to in two ways: either with a unique string name or their position as an integer. Columns can be named either when the table is created, or they can be (re)named dynamically with keywords. The integer position can always be used, and it starts from zero.

For instance, a table with columns “Name”, “Age”, and “Address” would allow referring to the “Age” column with either the name “Age” or the number 1.

Rows do not have a name, but instead only have an integer index. This index also starts from zero. Keywords where rows are indexed also support negative values, which start counting backwards from the end.

For instance, in a table with five rows, the first row could be referred to with the number 0. The last row could be accessed with either 4 or -1.

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: Table, name: Optional[str] = None, values: Optional[Any] = None)

Append a column to a table.

Parameters

  • table – Table to modify

  • name – Name of new column

  • values – Value(s) for new column

The values can either be a list of values, one for each row, or one single value that is set for all rows.

Examples:

# Add empty column
Add table column    ${table}

# Add empty column with name
Add table column    ${table}    name=Home Address

# Add new column where every every row has the same value
Add table column    ${table}    name=TOS    values=${FALSE}

# Add new column where every row has a unique value
${is_first}=    Create list    ${TRUE}    ${FALSE}    ${FALSE}
Add table column    ${table}    name=IsFirst    values=${is_first}
add_table_row(table: Table, values: Optional[Any] = None)

Append rows to a table.

Parameters

  • table – Table to modify

  • values – Value(s) for new row

The values can either be a list of values, or a dictionary where the keys match current column names. Values for unknown keys are discarded.

It can also be a single value that is set for all columns, which is None by default.

Examples:

# Add empty row
Add table row    ${table}

# Add row where every column has the same value
Add table row    ${table}    Unknown

# Add values per column
${values}=    Create dictionary    Username=Mark    Mail=mark@robocorp.com
Add table row    ${table}    ${values}
clear_table(table: Table)

Clear table in-place, but keep columns.

Parameters

table – Table to clear

Example:

Clear table    ${table}
copy_table(table: Table) → Table

Make a copy of a table object.

Parameters

table – Table to copy

Returns

Table object

${table_copy}= Copy table ${table}

create_table(data: Optional[Union[Dict[Union[int, str], Union[Dict, List, Tuple, NamedTuple, set]], List[Union[Dict, List, Tuple, NamedTuple, set]], Table]] = None, trim: bool = False, columns: Optional[List[str]] = None) → Table

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)

Returns

Table object

See the main library documentation for more information about supported data types.

Example:

# Create a new table using a Dictionary of Lists
# Because of the dictionary keys the column names will be automatically set
@{Table_Data_name}=    Create List    Mark    John    Amy
@{Table_Data_age}=    Create List    ${58}    ${22}    ${67}
&{Table_Data}=    Create Dictionary
...    name=${Table_Data_name}
...    age=${Table_Data_age}
${table}=    Create Table    ${Table_Data}
export_table(table: Table, with_index: bool = False, as_list: bool = True) → Union[List, Dict]

Convert a table object into 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

Returns

A List or Dictionary that represents the table

Example:

${orders}=       Read worksheet as table    orders.xlsx
Sort table by column    ${orders}    CustomerId
${export}=       Export table    ${orders}
# The following keyword expects a dictionary:
Write as JSON    ${export}
filter_empty_rows(table: Table)

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

Parameters

table – Table to filter

The filtering will be done in-place.

Example:

Filter empty rows    ${table}
filter_table_by_column(table: Table, column: Union[int, str], operator: str, value: Any)

Remove all rows where column values don’t 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)

See the keyword Find table rows for all supported operators and their descriptions.

The filtering will be done in-place.

Examples:

# Only accept prices that are non-zero
Filter table by column    ${table}   price  !=  ${0}

# Remove uwnanted product types
@{types}=    Create list    Unknown    Removed
Filter table by column    ${table}   product_type  not in  ${types}
filter_table_with_keyword(table: Table, name: str, *args)

Run a keyword for each row of a table, then remove all rows where the called keyword returns a falsy value.

Can be used to create custom RF keyword based filters.

Parameters

  • table – Table to modify.

  • name – Keyword name used as filter.

  • args – Additional keyword arguments to be passed. (optional)

The row object will be given as the first argument to the filtering keyword.

find_table_rows(table: Table, column: Union[int, str], operator: str, value: Any)

Find all the rows in a table which match a condition for a given column.

Parameters

  • table – Table to search into.

  • column – Name or position of the column to compare with.

  • operator – Comparison operator used with every cell value on the specified column.

  • value – Value to compare against.

Returns

New Table object containing all the rows matching the condition.

Supported operators:

Operator

Description

>

Cell value is larger than

<

Cell value is smaller than

>=

Cell value is larger or equal than

<=

Cell value is smaller or equal than

==

Cell value is equal to

!=

Cell value is not equal to

is

Cell value is the same object

not is

Cell value is not the same object

contains

Cell value contains given value

not contains

Cell value does not contain given value

in

Cell value is in given value

not in

Cell value is not in given value

Returns the matches as a new Table instance.

Examples:

# Find all rows where price is over 200
@{rows} =    Find table rows    ${table}    Price  >  ${200}

# Find all rows where the status does not contain "removed"
@{rows} =    Find table rows    ${table}    Status  not contains  removed
get_table_cell(table: Table, row: Union[int, str], column: Union[int, str]) → Any

Get a cell value from a table.

Parameters

  • table – Table to read from

  • row – Row of cell

  • column – Column of cell

Returns

Cell value

Examples:

# Get the value in the first row and first column
Get table cell    ${table}    0    0

# Get the value in the last row and first column
Get table cell    ${table}   -1    0

# Get the value in the last row and last column
Get table cell    ${table}   -1    -1

# Get the value in the third row and column "Name"
Get table cell    ${table}    2    Name
get_table_column(table: Table, column: Union[int, str]) → List

Get all values for a single column in a table.

Parameters

  • table – Table to read

  • column – Column to read

Returns

List of the rows in the selected column

Example:

${emails}=    Get table column    ${users}    E-Mail Address
get_table_dimensions(table: Table) → Tuple[int, int]

Return table dimensions, as (rows, columns).

Parameters

table – Table to inspect

Returns

Two integer values that represent the number of rows and columns

Example:

${rows}  ${columns}=    Get table dimensions    ${table}
Log    Table has ${rows} rows and ${columns} columns.
get_table_row(table: Table, row: Union[int, str], as_list: bool = False) → Union[Dict, List]

Get a single row from a table.

Parameters

  • table – Table to read

  • row – Row to read

  • as_list – Return list instead of dictionary

Returns

Dictionary or List of table row

Examples:

# returns the first row in the table
${first}=    Get table row    ${orders}

# returns the last row in the table
${last}=      Get table row    ${orders}    -1    as_list=${TRUE}
get_table_slice(table: Table, start: Optional[Union[int, str]] = None, end: Optional[Union[int, str]] = None) → Union[Table, List[List]]

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

Parameters

  • table – Table to read from

  • start – Start index (inclusive)

  • start – End index (exclusive)

Returns

Table object of the selected rows

If start is not defined, starts from the first row. If end is not defined, stops at the last row.

Examples:

# Get all rows except first five
${slice}=    Get table slice    ${table}    start=5

# Get rows at indexes 5, 6, 7, 8, and 9
${slice}=    Get table slice    ${table}    start=5    end=10

# Get all rows except last five
${slice}=    Get table slice    ${table}    end=-5
group_table_by_column(table: Table, column: Union[int, str]) → List[Table]

Group a 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

Returns

List of Table objects

Example:

# Groups rows of matching customers from the `customer` column
# and returns the groups or rows as Tables
@{groups}=    Group table by column    ${orders}    customer
# An example of how to use the List of Tables once returned
FOR    ${group}    IN    @{groups}
    # Process all orders for the customer at once
    Process order    ${group}
END
map_column_values(table: Table, column: Union[int, str], name: str, *args)

Run a keyword for each cell in a given column, and replace its content with the return value.

Can be used to easily convert column types or values in-place.

Parameters

  • table – Table to modify.

  • column – Column to modify.

  • name – Mapping keyword name.

  • args – Additional keyword arguments. (optional)

The cell value will be given as the first argument to the mapping keyword.

Examples:

# Convert all columns values to a different type
Map column values    ${table}    Price    Convert to integer

# Look up values with a custom keyword
Map column values    ${table}    User     Map user ID to name
merge_tables(*tables: Table, index: Optional[str] = None) → Table

Create a union of two tables and their contents.

Parameters

  • tables – Tables to merge

  • index – Column name to use as index for merge

Returns

Table object

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: Table, column: Optional[Union[int, str]] = None) → Union[Dict, List]

Remove column from table and return it.

Parameters

  • table – Table to modify

  • column – Column to remove

Returns

Dictionary or List of the removed, popped, column

Examples:

# Remove column from table and discard it
Pop table column    ${users}   userId

# Remove column from table and iterate over it
${ids}=    Pop table column    ${users}    userId
FOR    ${id}    IN    @{ids}
    Log    User id: ${id}
END
pop_table_row(table: Table, row: Optional[Union[int, str]] = None, as_list: bool = False) → Union[Dict, List]

Remove row from table and return it.

Parameters

  • table – Table to modify

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

  • as_list – Return list instead of dictionary

Returns

Dictionary or List of the removed, popped, row

Examples:

# Pop the firt row in the table and discard it
Pop table row    ${orders}

# Pop the last row in the table and store it
${row}=      Pop table row    ${data}    -1    as_list=${TRUE}
read_table_from_csv(path: str, header: Optional[bool] = None, columns: Optional[List[str]] = None, dialect: Optional[Dialect] = None, delimiters: Optional[str] = None, column_unknown: str = 'Unknown', encoding: Optional[str] = None) → Table

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

  • column_unknown – Column name for unknown fields

  • encoding – Text encoding for input file, uses system encoding by default

Returns

Table object

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.

If the source data has a header and rows have more fields than the header defines, the remaining values are put into the column given by column_unknown. By default it has the value “Unknown”.

Examples:

# Source dialect is deduced automatically
${table}=    Read table from CSV    export.csv
Log   Found columns: ${table.columns}

# Source dialect is known and given explicitly
${table}=    Read table from CSV    export-excel.csv    dialect=excel
Log   Found columns: ${table.columns}
rename_table_columns(table: Table, names: List[Optional[str]], strict: bool = False)

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

Parameters

  • table – Table to modify

  • names – List of new column names

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

The renaming will be done in-place.

Examples:

# Initially set the column names
${columns}=    Create list   First  Second  Third
Rename table columns    ${table}    ${columns}
# First, Second, Third

# Update the first and second column names to Uno and Dos
${columns}=    Create list   Uno  Dos
Rename table columns    ${table}    ${columns}
# Uno, Dos, Third
set_row_as_column_names(table: Table, row: Union[int, str])

Set existing row as names for columns.

Parameters

  • table – Table to modify

  • row – Row to use as column names

Example:

# Set the column names based on the first row
Set row as column names    ${table}    0
set_table_cell(table: Table, row: Union[int, str], column: Union[int, str], value: Any)

Set a cell value in a table.

Parameters

  • table – Table to modify to

  • row – Row of cell

  • column – Column of cell

  • value – Value to set

Examples:

# Set the value in the first row and first column to "First"
Set table cell    ${table}    0    0       First

# Set the value in the last row and first column to "Last"
Set table cell    ${table}   -1    0       Last

# Set the value in the last row and last column to "Corner"
Set table cell    ${table}   -1    -1       Corner

# Set the value in the third row and column "Name" to "Unknown"
Set table cell    ${table}    2    Name    Unknown
set_table_column(table: Table, column: Union[int, str], values: Any)

Assign values to a column in the table.

Parameters

  • table – Table to modify

  • column – Column to modify

  • values – Value(s) to set

The values can either be a list of values, one for each row, or one single value that is set for all rows.

Examples:

# Set different value for each row (sizes must match)
${ids}=    Create list    1  2  3  4  5
Set table column    ${users}    userId    ${ids}

# Set the same value for all rows
Set table column    ${users}    email     ${NONE}
set_table_row(table: Table, row: Union[int, str], values: Any)

Assign values to a row in the table.

Parameters

  • table – Table to modify

  • row – Row to modify

  • values – Value(s) to set

The values can either be a list of values, or a dictionary where the keys match current column names. Values for unknown keys are discarded.

It can also be a single value that is set for all columns.

Examples:

${columns}=  Create list     One  Two  Three
${table}=    Create table    columns=${columns}

${values}=   Create list     1  2  3
Set table row    ${table}    0    ${values}

${values}=   Create dictionary    One=1  Two=2  Three=3
Set table row    ${table}    1    ${values}

Set table row    ${table}    2    ${NONE}
sort_table_by_column(table: Table, column: Union[int, str], ascending: bool = True)

Sort a table in-place according to column.

Parameters

  • table – Table to sort

  • column – Column to sort with

  • ascending – Table sort order

Examples:

# Sorts the `order_date` column ascending
Sort table by column    ${orders}    order_date

# Sorts the `order_date` column descending
Sort table by column    ${orders}    order_date    ascending=${FALSE}
table_head(table: Table, count: int = 5, as_list: bool = False) → Union[Table, List[List]]

Return first count rows from a table.

Parameters

  • table – Table to read from

  • count – Number of lines to read

  • as_list – Return list instead of Table

Returns

Return Table object or List of the selected rows

Example:

# Get the first 10 employees
${first}=    Table head    ${employees}    10
table_tail(table: Table, count: int = 5, as_list: bool = False) → Union[Table, List[List]]

Return last count rows from a table.

Parameters

  • table – Table to read from

  • count – Number of lines to read

  • as_list – Return list instead of Table

Returns

Return Table object or List of the selected rows

Example:

# Get the last 10 orders
${latest}=    Table tail    ${orders}    10
trim_column_names(table: Table)

Remove all extraneous whitespace from column names.

Parameters

table – Table to filter

The filtering will be done in-place.

Example:

# This example will take colums such as:
# "One", "Two ", "  Three "
# and trim them to become the below:
# "One", "Two", "Three"
Trim column names     ${table}
trim_empty_rows(table: Table)

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

Parameters

table – Table to filter

The filtering will be done in-place.

Example:

Trim empty rows    ${table}
write_table_to_csv(table: Table, path: str, header: bool = True, dialect: Dialect = Dialect.Excel, encoding: Optional[str] = None, delimiter: Optional[str] = ',')

Write a table as a CSV file.

Parameters

  • table – Table to write

  • path – Path to write to

  • header – Write columns as header to CSV file

  • dialect – The format of output CSV

  • encoding – Text encoding for output file, uses system encoding by default

  • delimiter – Delimiter character between columns

Valid dialect values are Excel, ExcelTab, and Unix.

Example:

${sheet}=    Read worksheet as table    orders.xlsx    header=${TRUE}
Write table to CSV    ${sheet}    output.csv
RPA.Tables.if_none(value: Any, default: Any)

Return default if value is None.

RPA.Tables.iskeyword()

x.__contains__(y) <==> y in x.

RPA.Tables.return_table_as_raw_list(table, heading=False)
RPA.Tables.to_condition(operator: str, value: Any) → Callable[[Any], bool]

Convert string operator into callable condition function.

RPA.Tables.to_identifier(val: Any)

Convert string to valid identifier

RPA.Tables.to_list(obj: Any, size: int = 1)

Convert (possibly scalar) value to list of size.

RPA.Tables.uniq(seq: Iterable)

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