Metadata-Version: 2.3
Name: transmog
Version: 1.1.0
Summary: A data transformation library for flattening complex nested structures into tabular formats while preserving hierarchical relationships
License: MIT
Keywords: csv,data-pipeline,data-processing,data-transformation,elt,etl,flattening,json,normalization,parquet,pyarrow
Author: Scott Draper
Author-email: admin@scottdraper.io
Requires-Python: >=3.9
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: dev
Provides-Extra: minimal
Requires-Dist: bandit (>=1.7.5) ; extra == "dev"
Requires-Dist: furo (>=2024.1.29) ; extra == "dev"
Requires-Dist: interrogate (>=1.5) ; extra == "dev"
Requires-Dist: linkify-it-py (>=2) ; extra == "dev"
Requires-Dist: memory-profiler (>=0.60) ; extra == "dev"
Requires-Dist: mypy (>=0.9) ; extra == "dev"
Requires-Dist: myst-parser (>=2) ; extra == "dev"
Requires-Dist: orjson (>=3.8)
Requires-Dist: polars (>=0.20)
Requires-Dist: pre-commit (>=3.5) ; extra == "dev"
Requires-Dist: psutil (>=5.8) ; extra == "dev"
Requires-Dist: pyarrow (>=7)
Requires-Dist: pyproject-fmt (>=1.5.1) ; extra == "dev"
Requires-Dist: pyproject-parser (>=0.7) ; extra == "dev"
Requires-Dist: pytest (>=7) ; extra == "dev"
Requires-Dist: pytest-benchmark (>=4) ; extra == "dev"
Requires-Dist: pytest-cov (>=3) ; extra == "dev"
Requires-Dist: ruff (>=0.3) ; extra == "dev"
Requires-Dist: safety (>=2.3.5) ; extra == "dev"
Requires-Dist: sphinx (>=7.2) ; extra == "dev"
Requires-Dist: sphinx-autobuild (>=2021.3.14) ; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints (>=1.24) ; extra == "dev"
Requires-Dist: sphinx-copybutton (>=0.5) ; extra == "dev"
Requires-Dist: sphinx-design (>=0.5) ; extra == "dev"
Requires-Dist: sphinx-rtd-theme (>=2) ; extra == "dev"
Requires-Dist: sphinxcontrib-applehelp (>=1) ; extra == "dev"
Requires-Dist: sphinxcontrib-htmlhelp (>=2) ; extra == "dev"
Requires-Dist: sphinxcontrib-jsmath (>=1) ; extra == "dev"
Requires-Dist: sphinxcontrib-mermaid (>=0.8.1) ; extra == "dev"
Requires-Dist: sphinxcontrib-napoleon (>=0.7) ; extra == "dev"
Requires-Dist: sphinxcontrib-qthelp (>=1) ; extra == "dev"
Requires-Dist: sphinxcontrib-serializinghtml (>=1) ; extra == "dev"
Requires-Dist: types-pyyaml ; extra == "dev"
Requires-Dist: types-toml ; extra == "dev"
Requires-Dist: typing-extensions (>=4)
Project-URL: Bug Tracker, https://github.com/scottdraper8/transmog/issues
Project-URL: Documentation, https://scottdraper8.github.io/transmog/
Project-URL: Homepage, https://github.com/scottdraper8/transmog
Description-Content-Type: text/markdown

# Transmog

[![PyPI version](https://img.shields.io/pypi/v/transmog.svg?logo=pypi)](https://pypi.org/project/transmog/)
[![Python versions](https://img.shields.io/badge/python-3.9%2B-blue?logo=python)](https://pypi.org/project/transmog/)
[![License](https://img.shields.io/github/license/scottdraper8/transmog.svg?logo=github)](https://github.com/scottdraper8/transmog/blob/main/LICENSE)

Transform nested data into flat tables with a simple, intuitive API.

## Overview

Transmog transforms nested JSON data into flat, tabular formats while preserving relationships between parent and child records.

**Key Features:**

- Simple one-function API with smart defaults
- Multiple output formats (JSON, CSV, Parquet)
- Automatic relationship preservation
- Memory-efficient streaming for large datasets

## Quick Start

```bash
pip install transmog
```

```python
import transmog as tm

# Transform nested data into flat tables
result = tm.flatten({"name": "Product", "specs": {"cpu": "i7", "ram": "16GB"}})
print(result.main)  # Flattened data: [{'name': 'Product', 'specs_cpu': 'i7', ...}]

# Save in any format
result.save("output.json")
```

## Example

Transform complex nested data into relational tables:

```python
data = {
    "user": {"name": "Alice", "email": "alice@example.com"},
    "orders": [
        {"id": 101, "amount": 99.99},
        {"id": 102, "amount": 45.50}
    ]
}

result = tm.flatten(data, name="customer")

# Main table: [{'user_name': 'Alice', 'user_email': 'alice@...', '_id': '...'}]
# Orders table: [{'id': 101, 'amount': 99.99, '_parent_id': '...'}, ...]
```

**Key Options:**

- Custom field separators: `separator="."`
- Use existing IDs: `id_field="customer_id"`
- Error handling: `errors="skip"`
- File processing: `tm.flatten_file("data.json")`

## Advanced Options

For more control:

```python
result = tm.flatten(
    data,
    name="products",
    # Naming
    separator=".",              # Use dots: user.name
    nested_threshold=3,         # Simplify deeply nested names
    # IDs
    id_field="sku",            # Use existing field as ID
    parent_id_field="_parent",  # Customize parent reference name
    add_timestamp=True,         # Add timestamp to records
    # Arrays
    arrays="inline",           # Keep arrays as JSON instead of separate tables
    # Data handling
    preserve_types=True,       # Keep original types (don't convert to strings)
    skip_null=False,           # Include null values
    skip_empty=False,          # Include empty strings/lists
    # Performance
    batch_size=5000,           # Process in larger batches
    low_memory=True,           # Optimize for low memory usage
)
```

## Documentation

Complete documentation is available at
[scottdraper8.github.io/transmog](https://scottdraper8.github.io/transmog), including:

- [Quick Start Guide](https://scottdraper8.github.io/transmog/quickstart.html)
- [User Guides](https://scottdraper8.github.io/transmog/guides/)
- [API Reference](https://scottdraper8.github.io/transmog/reference/)
- [Advanced Topics](https://scottdraper8.github.io/transmog/advanced/)

## Contributing

For contribution guidelines, development setup, and coding standards,
see the [Contributing Guide](https://scottdraper8.github.io/transmog/development/contributing.html)
in the documentation.

## License

MIT License

