pandas2toon

A Python library for seamless conversion between pandas DataFrames and TOON (Tabular Object Oriented Notation) format. This library simplifies working with TOON files by providing easy-to-use functions for reading and writing structured data with support for nested structures.

Features

• Read TOON files: Convert TOON files into pandas DataFrames
• Write TOON files: Export pandas DataFrames into TOON format
• Support for nested structures: Options to flatten nested data or handle it at specified depths
• Customizable formatting: Control TOON output format, indentation, and delimiters
• Flexible I/O: Work with file paths, file-like objects, or strings

Requirements

• Python 3.7 or higher
• pandas >= 1.0.0

Installation

Install via pip:

pip install pandas2toon

Quick Start

from pandas2toon import read_toon, to_toon

# Read a TOON file into a DataFrame
df = read_toon("data.toon")

# Convert a DataFrame to TOON format
toon_string = to_toon(df)

# Save directly to a file
to_toon(df, "output.toon")

Usage Guide

Reading TOON Files

Use the read_toon function to convert TOON files into pandas DataFrames:

# Basic usage
df = read_toon("data.toon")

# Flatten nested structures
df = read_toon("data.toon", flatten_nested=True, nested_depth=0)

# Specify format type
df = read_toon("data.toon", format_type="tabular_array")

read_toon Parameters

• file_path (str | TextIO): Path to the TOON file or file-like object
• flatten_nested (bool, default=False): Whether to flatten nested structures into columns
• nested_depth (int, default=0): Maximum depth to flatten (0 = fully flatten)
• format_type (str, default="object"): Reader format mode ("object", "tabular_array", "nested_dict")

Example with Nested Data

# Given a TOON file with nested structure:
df = read_toon("nested_data.toon", flatten_nested=True, nested_depth=0)
print(df)

Output:

   id  personal.name  personal.contact_details.email.address  \
0   1         Alice                      alice@example.com   

  personal.contact_details.address.street  \
0                     123 Wonderland Blvd   

  personal.contact_details.address.city  personal.contact_details.address.country
0                            Wonderland                          Fantasyland

Writing TOON Files

Convert pandas DataFrames to TOON format using the to_toon function:

Option 1: Return as String

df = pd.DataFrame([
    {"id": 1, "name": "Alice", "scores": [85, 90, 95], "details": {"age": 20, "city": "NY"}},
    {"id": 2, "name": "Bob", "scores": [78, 82, 88], "details": {"age": 22, "city": "LA"}}
])

# Convert to TOON string
toon_str = to_toon(df)
print(toon_str)

Output:

[2]:
  - id: 1
    name: Alice
    scores[3]: 85,90,95
    details:
      age: 20
      city: NY
  - id: 2
    name: Bob
    scores[3]: 78,82,88
    details:
      age: 22
      city: LA

Option 2: Custom Formatting

# Customize output with indentation and delimiter
toon_str = to_toon(df, indent=4, delimiter="|", format_type="tabular_array")
print(toon_str)

Output:

[2|]:
    - id: 1
      name: Alice
      scores[3|]: 85|90|95
      details:
          age: 20
          city: NY
    - id: 2
      name: Bob
      scores[3|]: 78|82|88
      details:
          age: 22
          city: LA

Option 3: Save Directly to File

# Write to file with confirmation message
message = to_toon(
    df, 
    file_path="output.toon",
    indent=2,
    delimiter="|",
    format_type="tabular_array",
    return_message=True
)
print(message)
# Output: Successfully saved TOON file at: output.toon

to_toon Parameters

• df (DataFrame): Input pandas DataFrame to convert
• file_path (str | TextIO | None, default=None): File path or buffer to write output. If None, returns string
• table_name (str | None, default=None): Optional table name header in TOON format
• delimiter (str, default=","): Column separator for TOON table mode
• indent (int, default=2): Number of spaces for indentation
• length_marker (str, default=""): Marker for length-prefixed fields ("" or "#")
• format_type (str, default="tabular_array"): TOON formatting mode ("tabular_array", "nested_dict", "auto")
• return_message (bool, default=False): Return success message when saving to file

API Reference

read_toon(file_path, flatten_nested=False, nested_depth=0, format_type="object")

Reads a TOON file and converts it to a pandas DataFrame.

Returns: pandas DataFrame

to_toon(df, file_path=None, table_name=None, delimiter=",", indent=2, length_marker="", format_type="tabular_array", return_message=False)

Converts a pandas DataFrame to TOON format.

Returns: str | None (TOON string if file_path is None, otherwise None or success message)

Use Cases

• Data Serialization: Store complex, nested data structures in a human-readable format
• Configuration Files: Use TOON format for application configuration with nested settings
• Data Exchange: Share structured data between applications that support TOON format
• Data Archival: Archive pandas DataFrames in a format that preserves structure and is easy to read

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please visit the project repository or open an issue on GitHub.