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:
An iterable of individual rows, like a list of lists, or list of dictionaries
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 areexcel
,excel-tab
, andunix
, andheader
is boolean argument (True
/False
). Optionally a set of validdelimiters
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 areexcel
,excel-tab
, andunix
.
-
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.