robotframework-tablelibrary 0.1.4
A Robot Framework library providing generic table keywords for several table file type like csv or excel.
License: Apache-2.0
Requires Python: >=3.10

<div align="center">
  <h1>RobotFramework Table Library</h1>
</div>
<div align="center">
  <img src="utils/imbus-web-logo.svg">
</div>


## Statistics

[![Latest Build Status -  Branch](https://img.shields.io/github/actions/workflow/status/imbus/robotframework-tablelibrary/release.yml?label=Release%20Creation)](https://github.com/imbus/robotframework-tablelibrary/actions/workflows/release.yml)
[![Latest Build Status - Default Branch](https://img.shields.io/github/actions/workflow/status/imbus/robotframework-tablelibrary/build.yml?branch=main&label=Build%20Status%20-%20Default%20Branch)](https://github.com/imbus/robotframework-tablelibrary/actions/workflows/build.yml)
[![PyPI - Version](https://img.shields.io/pypi/v/robotframework-tablelibrary.svg)](https://pypi.org/project/robotframework-tablelibrary)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/robotframework-tablelibrary.svg)](https://pypi.org/project/robotframework-tablelibrary)
[![PyPI Downloads - Total](https://static.pepy.tech/badge/robotframework-tablelibrary)](https://pepy.tech/projects/robotframework-tablelibrary)
[![PyPI Downloads - Monthly](https://static.pepy.tech/badge/robotframework-tablelibrary/month)](https://pepy.tech/projects/robotframework-tablelibrary)

## Keyword Documentation

Here you can find the **[Keyword Documentation](https://imbus.github.io/robotframework-tablelibrary/keywords.html)** generated by ``libdoc``.

## 📊 RobotFramework TableLibrary

**TableLibrary** is a Robot Framework library designed for easy handling of tabular data formats such as **CSV**, **Excel**, **Parquet**, and more.  
It provides a unified interface for **reading**, **modifying**, and **creating** tables directly within your Robot Framework tests.

### 🔍 Key Features

- **Read Tables**
  - Supports formats like `.csv`, `.xlsx`, `.xls`, `.parquet`, `.json`, `.txt (as csv)`, and more.
  - Access table contents by column name or index.
  - Verifying specific table cells, columns or rows & executing assertions using the ``robotframework-assertion-engine``

- **Modify Existing Tables**
  - Add, remove, or update rows and columns.
  - Apply dynamic modifications during test execution.

- **Create New Tables**
  - Create tables from lists, dictionaries, or other data sources.
  - Export tables to multiple file formats (e.g., CSV, Excel, Parquet).
  - Easily generate structured test data in the given file format.

### Exception: Excel File Handling

We have included a basic handling of ``Excel`` files, but for more complex excel features, please take a look at the following library: **[robotframework-excelsage](https://pypi.org/project/robotframework-excelsage)**

This library got especially written to work with more complex ``Excel`` features like e.g. ``Excel Sheets``, etc...

## Installation

You can install the library using the following command:
```console
pip install robotframework-tablelibrary
```

## Example

### File Format - CSV


```
# Reading CSV file with header column
${content} =    Tables.Read Table    ${CURDIR}${/}testdata${/}example_01.csv
${result} =    BuiltIn.Evaluate    "${content}[0][0]" == "index"
BuiltIn.Should Be True    ${result}
```

```
# Reading CSV file without header column
Tables.Configure Ignore Header    True
${content} =    Tables.Read Table    ${CURDIR}${/}testdata${/}example_01.csv
${result} =    BuiltIn.Evaluate    "index" not in "${content}"
BuiltIn.Should Be True    ${result}
```

### File Format - Parquet
```
${content} =    Tables.Read Table    ${CURDIR}${/}testdata${/}example_05.parquet
${result} =    BuiltIn.Evaluate    "${content}[0][0]" == "_time"
BuiltIn.Should Be True    ${result}
```

### Create new empty table - don't save to file system
```
# Create some data which should be inserted into the new table
VAR    @{headers} =    name    age
VAR    @{person1} =    Michael    34
VAR    @{person2} =    John    19

# Create empty table object - internally in cache
${uuid} =    Tables.Create Table    headers=${headers}

# Append some rows
Tables.Append Row    ${person1}
Tables.Append Row    ${person2}
Count Table    ${uuid}    Rows    equal    ${3}

# Append a column
VAR    @{column1} =    city    MG    ERL
Tables.Append Column    ${column1}
Count Table    ${uuid}    Columns    equal    ${3}

# Optional: Set new table cell value
Get Table Cell    1    1    equals    34
Tables.Set Table Cell    25    0    1
Get Table Cell    1    1    equals    25

# Insert a new row into the existing table object
VAR    @{insert_row} =    Lu    26    Hamburg
Insert Row    ${insert_row}    0
Get Table Cell    1    0    equals    Lu
Count Table    ${uuid}    Rows    equal    ${4}
```

### Create new empty table - save to file system
```
# Generate new headers which should be used in the table
VAR    @{headers} =    name    age

# Create new table object
${uuid} =    Create Table    ${headers}

# Generate some random data & append as rows to new table
FOR    ${_}    IN RANGE    ${100}
    ${a} =    Generate Random String
    ${b} =    Generate Random String
    VAR    @{data}    ${a}    ${b}
    Tables.Append Row    ${data}
END

# Ensure that data got written into internal table object
Count Table    ${uuid}    Rows    equals    ${101}

# Write table to specific file path -> write from cache into persistant file
Write Table    ${uuid}    ${CURDIR}/results/test_writer_new_table.csv

# Check table content again, but now read table from file path!
Count Table    ${CURDIR}/results/test_writer_new_table.csv    Rows    equals    ${101}
```

## Contribution & Development

See [Development.md](./DEVELOPMENT.md) for more information about contributing & developing this library.

## License

``robotframework-tablelibrary`` is distributed under the terms of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) license.