Metadata-Version: 2.4
Name: json_to_many
Version: 0.2.0
Summary: A utility package to convert JSON data to multiple formats like XML, Markdown, CSV, etc.
Project-URL: Homepage, https://github.com/ananthanandanan/Json_To_Many
Project-URL: Repository, https://github.com/ananthanandanan/Json_To_Many
Project-URL: Documentation, https://github.com/ananthanandanan/Json_To_Many/tree/main?tab=readme-ov-file#quick-start
Project-URL: Bug Reports, https://github.com/ananthanandanan/Json_To_Many/issues
Author-email: ananthanandanan <ananthanandanan@gmail.com>
License: MIT License
        
        Copyright (c) 2026 K N Anantha nandanan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: converter,csv,json,markdown,xml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Utilities
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown

# Json_To_Many

[![PyPI Version](https://img.shields.io/pypi/v/json_to_many.svg)](https://pypi.org/project/json_to_many/)
[![License](https://img.shields.io/pypi/l/json_to_many.svg)](https://github.com/ananthanandanan/Json_To_Many/blob/main/LICENSE)
[![Build Status](https://github.com/ananthanandanan/Json_To_Many/actions/workflows/ci.yml/badge.svg)](https://github.com/ananthanandanan/Json_To_Many/actions)

## Overview

In today's interconnected digital ecosystem, **JSON has become the lingua franca of data exchange**. From REST APIs to configuration files, from database exports to IoT sensor data, JSON is everywhere. However, while JSON excels at machine-to-machine communication, different tools, platforms, and use cases often require data in specific formats.

**Json_To_Many** bridges this gap by providing seamless conversion from JSON to multiple output formats. Whether you're a developer documenting an API, a data analyst preparing reports, or a content creator transforming data for different platforms, this package eliminates the friction of manual format conversion.

### The Problem We Solve

- **Developers** need to transform API responses for documentation (Markdown)
- **Data analysts** require CSV exports for spreadsheet analysis
- **DevOps teams** need XML for legacy system integration
- **Content creators** want structured data in readable formats
- **Business users** need reports generated from JSON APIs

**Json_To_Many** makes these transformations effortless, allowing you to focus on what matters most: your data and insights.

The project is managed using **uv** for dependency management and packaging, and **Ruff** is used for linting to ensure code quality.

> **Note:** This is a humble side project built out of passion for making data format conversions easier and more accessible.

## Features

### Current Supported Formats

- **JSON to Markdown**
- **JSON to XML**
- **JSON to CSV**

### Upcoming Supported Formats

- **JSON to TSV**
- **JSON to SQL**
- **JSON to YAML**
- **JSON to HTML**
- **JSON to PDF**

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
  - [Converting JSON to Markdown](#converting-json-to-markdown)
    - [Markdown Options](#markdown-options)
  - [Converting JSON to XML](#converting-json-to-xml)
  - [Converting JSON to CSV](#converting-json-to-csv)
- [Examples](#examples)
- [Development](#development)
  - [Setting Up a Development Environment](#setting-up-a-development-environment)
  - [Coding Guidelines](#coding-guidelines)
- [Contributing](#contributing)
- [Roadmap](#roadmap)
- [License](#license)
- [Contact](#contact)

## Installation

Install **Json_To_Many** using `pip`:

```bash
pip install json_to_many
```

Or, if you prefer using uv:

```bash
uv add json_to_many
```

## Quick Start

```python
from json_to_many import convert

# Convert JSON string to Markdown and save to 'output.md'
json_string = '{"title": "Sample Document", "content": "This is a sample."}'
convert(json_string, 'markdown', output_file='output.md')

# Convert JSON file to XML and get the converted data
xml_data = convert('data.json', 'xml', return_data=True)
print(xml_data)
```

## Usage

### Converting JSON to Markdown

**From a JSON File:**

```python
from json_to_many import convert

# Convert JSON file to Markdown and save to 'output.md'
convert('data.json', 'markdown', output_file='output.md')
```

**From a JSON String:**

```python
from json_to_many import convert

json_string = '{"title": "Sample Document", "content": "This is a sample."}'

# Convert JSON string to Markdown and get the converted data
markdown_data = convert(json_string, 'markdown', return_data=True)
print(markdown_data)
```

**Sample Output:**

```markdown
# title

Sample Document

# content

This is a sample.
```

### Markdown Options

The Markdown converter accepts optional keyword arguments to customise its output. All options are passed directly to `convert()`.

#### Layout options

| Option | Type | Default | Description |
|---|---|---|---|
| `title` | `str` | `None` | Prepends `# {title}` at the top of the document |
| `heading_offset` | `int` | `0` | Shifts all heading levels by this amount (e.g. `1` makes top-level keys H2) |
| `max_heading_level` | `int` | `6` | Keys deeper than this render as `**bold**` instead of headings |
| `bullet_lists` | `bool` | `True` | Renders lists of primitives as `- item` bullet points |

**Example:**

```python
from json_to_many import convert

data = {
    "Project": {
        "Name": "MyApp",
        "Tech": ["Python", "FastAPI"],
    }
}

# Shift headings down one level and add a document title
md = convert(data, "markdown", return_data=True,
             title="Project Report",
             heading_offset=1,
             bullet_lists=True)
print(md)
```

```markdown
# Project Report

## Project

### Name

MyApp

### Tech

- Python
- FastAPI
```

#### Tables

| Option | Type | Default | Description |
|---|---|---|---|
| `table_for_lists` | `bool` | `False` | Renders a list of dicts with common keys as a GFM pipe table |

**Example:**

```python
data = {
    "Users": [
        {"name": "Alice", "role": "admin"},
        {"name": "Bob",   "role": "user"},
    ]
}

md = convert(data, "markdown", return_data=True, table_for_lists=True)
```

```markdown
# Users

| name | role |
| --- | --- |
| Alice | admin |
| Bob | user |
```

#### Frontmatter

| Option | Type | Default | Description |
|---|---|---|---|
| `frontmatter` | `dict` | `None` | Emits a YAML frontmatter block (for static site generators, Obsidian, etc.) |

Supports `str`, `int`, `float`, `bool`, and `None` values. No external dependencies required.

**Example:**

```python
md = convert(data, "markdown", return_data=True,
             frontmatter={"title": "API Docs", "date": "2025-02-21", "draft": False})
```

```markdown
---
title: API Docs
date: 2025-02-21
draft: false
---

...content...
```

#### Code blocks

| Option | Type | Default | Description |
|---|---|---|---|
| `code_block_keys` | `list` | `[]` | Values for these keys are rendered as fenced code blocks |

**Example:**

```python
data = {
    "endpoint": "/users",
    "example_request": '{"filter": "active"}',
}

md = convert(data, "markdown", return_data=True,
             code_block_keys=["example_request"])
```

```markdown
# endpoint

/users

# example_request

\`\`\`example_request
{"filter": "active"}
\`\`\`
```

### Converting JSON to XML

**From a Python Dictionary:**

```python
from json_to_many import convert

json_data = {
    "note": {
        "to": "Alice",
        "from": "Bob",
        "message": "Hello, Alice!"
    }
}

# Convert JSON data to XML and save to 'note.xml'
convert(json_data, 'xml', output_file='note.xml')
```

**Get Converted XML Data Without Saving:**

```python
xml_data = convert(json_data, 'xml', return_data=True)
print(xml_data)
```

**Sample Output:**

```xml
<root><note><to>Alice</to><from>Bob</from><message>Hello, Alice!</message></note></root>
```

### Converting JSON to CSV

**From a Python List of Dictionaries:**

```python
from json_to_many import convert

json_data = [
    {"name": "Alice", "age": 30, "city": "New York"},
    {"name": "Bob", "age": 25, "city": "Los Angeles"}
]

# Convert JSON data to CSV and save to 'data.csv'
convert(json_data, 'csv', output_file='data.csv')
```

**Get Converted CSV Data Without Saving:**

```python
csv_data = convert(json_data, 'csv', return_data=True)
print(csv_data)
```

**Sample Output:**

```csv
name,age,city
Alice,30,New York
Bob,25,Los Angeles
```

**Note:** The CSV converter automatically flattens nested JSON structures and handles complex data types appropriately.

## Examples

The `examples` directory contains sample scripts and data to help you get started.

- **JSON to Markdown Conversion**: [json_to_markdown_example.py](examples/json_to_markdown_example.py)
- **JSON to XML Conversion**: [json_to_xml_example.py](examples/json_to_xml_example.py)
- **JSON to CSV Conversion**: [json_to_csv_example.py](examples/json_to_csv_example.py)

### Running Examples

1. **Clone the Repository**:

   ```bash
   git clone https://github.com/ananthanandanan/Json_To_Many.git
   cd Json_To_Many/examples
   ```

2. **Install Dependencies** (for development):

   ```bash
   uv sync
   ```

   Or install the package directly:

   ```bash
   pip install json_to_many
   ```

3. **Run an Example Script**:

   ```bash
   uv run python json_to_markdown_example.py
   # or if installed globally:
   python json_to_markdown_example.py
   ```

## Development

The project uses **uv** for dependency management and packaging, and **Ruff** for linting and code style enforcement.

### Setting Up a Development Environment

1. **Fork the Repository**:

   Click the "Fork" button at the top right corner of the repository page.

2. **Clone Your Fork**:

   ```bash
   git clone https://github.com/ananthanandanan/Json_To_Many.git
   cd Json_To_Many
   ```

3. **Install Dependencies**:

   ```bash
   uv sync
   ```

4. **Run Tests**:

   ```bash
   uv run pytest
   ```

5. **Check Code Quality with Ruff**:

   ```bash
   uv run ruff check .
   ```

6. **Build the Package**:

   ```bash
   uv build
   ```

### Coding Guidelines

- **Code Style**: Follow PEP 8 guidelines. Use **Ruff** for linting and code style enforcement.
- **Testing**: Write unit tests for new features and bug fixes.
- **Documentation**: Update documentation and examples to reflect changes.

> **Maintainers:** See [RELEASING.md](RELEASING.md) for the full release process (version bump, tagging, GitHub Release, and PyPI publish).

## Contributing

Contributions are welcome! Here's how you can help:

- **Report Bugs**: If you find a bug, please report it by opening an issue.
- **Suggest Features**: Have an idea for a new feature? Feel free to share it.
- **Submit Pull Requests**: If you'd like to fix a bug or implement a feature, you're welcome to contribute code.

### Guidelines for Contributing

1. **Create an Issue**:

   Before starting work on a feature or bug fix, please create an issue to discuss it.

2. **Branch Naming**:

   Use descriptive branch names, e.g., `feature/json-to-yaml` or `bugfix/fix-xml-output`.

3. **Pull Requests**:
   - Include a clear description of the changes.
   - Reference the issue number.
   - Ensure all tests pass and code quality checks are successful.

4. **Code Quality**:
   - Run `uv run pytest` to ensure all tests pass.
   - Run `uv run ruff check .` to ensure code style compliance.

_For detailed technical specifications, implementation timelines, and architecture diagrams, see our comprehensive [**ROADMAP.md**](ROADMAP.md)._

_Want to contribute to this roadmap? Check out our [Contributing](#contributing) guidelines or open an issue to discuss new ideas!_

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contact

For questions or support, please open an issue or contact [K N Anantha nandanan](mailto:ananthanandanan@gmail.com).

---
