Json_To_Many

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
• Quick Start
• Usage
  • Converting JSON to Markdown
    • Markdown Options
  • Converting JSON to XML
  • Converting JSON to CSV
• Examples
• Development
  • Setting Up a Development Environment
  • Coding Guidelines
• Contributing
• Roadmap
• License
• Contact

Installation

Install Json_To_Many using pip:

pip install json_to_many

Or, if you prefer using uv:

uv add json_to_many

Quick Start

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:

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:

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:

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

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)

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

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

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

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

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

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

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

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

# endpoint

/users

# example_request

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

Converting JSON to XML

From a Python Dictionary:

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:

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

Sample Output:

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

Converting JSON to CSV

From a Python List of Dictionaries:

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:

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

Sample Output:

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
• JSON to XML Conversion: json_to_xml_example.py
• JSON to CSV Conversion: json_to_csv_example.py

Running Examples

1. Clone the Repository:

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

2. Install Dependencies (for development):

   uv sync

   Or install the package directly:

   pip install json_to_many

3. Run an Example Script:

   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:

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

3. Install Dependencies:

   uv sync

4. Run Tests:

   uv run pytest

5. Check Code Quality with Ruff:

   uv run ruff check .

6. Build the Package:

   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 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.

Want to contribute to this roadmap? Check out our Contributing guidelines or open an issue to discuss new ideas!

License

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

Contact

For questions or support, please open an issue or contact K N Anantha nandanan.

---