.. _example_csv_table:

CSV Table Upload/Download
=========================

This example uploads CSV data as rich-text HTML tables in LabArchives and can
download those tables back to CSV later. It is a good fit when you want
readable tables in the notebook UI without losing a machine-friendly export
path.

When to Use It
--------------

This is useful for:

- Uploading experimental data tables for visual display in notebooks.
- Creating formatted data tables that stay readable in the web interface.
- Extracting tabular data back to CSV for downstream analysis.
- Documenting datasets with consistent structure.
- Sharing tables with collaborators in a readable format.

Requirements
------------

This example assumes the recommended local interactive profile,
``labapi[dotenv,builtin-auth]``. See :ref:`installation`.

It also requires ``beautifulsoup4`` for HTML table parsing during download.

Configuration
-------------

For the local interactive workflow, create a ``.env`` file in the repository
root:

.. code-block:: toml

   API_URL="https://api.labarchives.com"
   ACCESS_KEYID="your_access_key_id"
   ACCESS_PWD="your_password"

You can also provide the same values through shell environment variables. See
:ref:`first_calls` for both options.

How It Works
------------

Upload Flow
~~~~~~~~~~~

- Read CSV data from disk.
- Convert it to HTML table markup.
- Upload the HTML as a rich-text entry.

Download Flow
~~~~~~~~~~~~~

- Find a text entry containing an HTML table.
- Parse the table back into structured data.
- Write the result to a CSV file.

Common Commands
---------------

Upload the checked-in sample CSV file:

.. code-block:: bash

   uv run --with beautifulsoup4 python examples/csv_table/csv_table.py upload examples/csv_table/sample_data.csv "Experiments/Results" --notebook "My Notebook"

Upload a CSV file that does not include a header row:

.. code-block:: bash

   uv run --with beautifulsoup4 python examples/csv_table/csv_table.py upload examples/csv_table/sample_data.csv "Experiments/Results" --notebook "My Notebook" --no-header

Download the most recent table from a page:

.. code-block:: bash

   uv run --with beautifulsoup4 python examples/csv_table/csv_table.py download "Experiments/Results" ./output/results.csv --notebook "My Notebook"

Download a specific table entry by index:

.. code-block:: bash

   uv run --with beautifulsoup4 python examples/csv_table/csv_table.py download "Experiments/Results" ./output/results.csv --notebook "My Notebook" --entry-index 2

Example CSV Input
-----------------

Given this CSV file (``examples/csv_table/sample_data.csv``):

.. code-block:: text

   Experiment,Temperature,Pressure,Result
   Trial 1,25.0,101.3,Success
   Trial 2,30.0,101.3,Success
   Trial 3,35.0,102.1,Failure

The script will generate this HTML table:

.. code-block:: html

   <table>
     <thead>
       <tr>
         <th>Experiment</th>
         <th>Temperature</th>
         <th>Pressure</th>
         <th>Result</th>
       </tr>
     </thead>
     <tbody>
       <tr>
         <td>Trial 1</td>
         <td>25.0</td>
         <td>101.3</td>
         <td>Success</td>
       </tr>
       <tr>
         <td>Trial 2</td>
         <td>30.0</td>
         <td>101.3</td>
         <td>Success</td>
       </tr>
       <tr>
         <td>Trial 3</td>
         <td>35.0</td>
         <td>102.1</td>
         <td>Failure</td>
       </tr>
     </tbody>
   </table>

The table is displayed with LabArchives' default styling.

Notes and Limitations
---------------------

- Tables are uploaded as rich-text entries, making them readable in the
  LabArchives web interface.
- Tables are rendered with LabArchives' default styling and no inline CSS.
- The script preserves table structure and can round-trip CSV to HTML and back
  to CSV.
- Multiple tables on one page are supported; by default, the download uses the
  most recent table.
- Empty cells in CSV files are preserved in the HTML table.
- CSV files with special characters should use UTF-8 encoding.
- Complex nested tables are not supported.
- Only the first table is extracted if an entry contains multiple tables.

Ways to Extend It
-----------------

1. Export multiple tables from one page to separate CSV files.
2. Handle ``colspan`` and ``rowspan`` attributes.
3. Validate CSV structure before upload.
4. Read from and write to XLSX files.
5. Generate charts from CSV data and upload them as images.
6. Support HTML table captions.

Source Code
-----------

.. literalinclude:: ../../../examples/csv_table/csv_table.py
   :language: python

Related Pages
-------------

- :doc:`index` for the full examples catalog.
- :ref:`writing_rich_text` for the underlying HTML entry model.
- :ref:`first_calls` for local authentication setup.