pandas2toon 0.1.0
A TOON format reader and writer extension for pandas.
Requires Python: >=3.8
Keywords: pandas, TOON format, serialization, dataframe, custom formatter, parser, writer, reader, read_toon, to_toon

# 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:

```bash
pip install pandas2toon
```

## Quick Start

```python
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:

```python
# 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

```python
# 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

```python
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:
```yaml
[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

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

Output:
```yaml
[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

```python
# 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](LICENSE) file for details.

## Support

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