Json2Many

A zero-dependency Python library and CLI for converting JSON into multiple output formats. Every conversion returns a typed ConversionResult — no raw string parsing, full mypy/pyright support out of the box.

→ User Guide — scenario-driven walkthrough of every feature

---

Installation

# Library only
pip install json_to_many

# With CLI support
pip install 'json_to_many[cli]'

Quick Start

Library:

from json_to_many import convert

result = convert("users.json", "csv", delimiter=";")
print(result.data)
# id,name,email,score,city
# 1,Alice Nguyen,alice@example.com,8.4,London
# 2,Bob Smith,bob@example.com,7.1,Berlin
print(result.stats.rows)    # 5

convert() also accepts Pydantic models, dataclasses, and any object exposing to_dict() — single instances or lists, including nested fields:

from dataclasses import dataclass
from pydantic import BaseModel
from json_to_many import convert

class User(BaseModel):
    id: int
    name: str

@dataclass
class Order:
    id: int
    total: float

convert([User(id=1, name="Alice"), User(id=2, name="Bob")], "csv")
convert([Order(id=10, total=42.5)], "markdown")

Pydantic v1? Pass .dict() yourself — only v2's model_dump() is auto-detected.

CLI:

# Inspect a JSON file before converting
json2many schema api_export.json

# Convert to CSV
json2many convert api_export.json --to csv --output report.csv

# Multiple formats in one pass
json2many convert api_export.json --to csv --to html --output-dir ./dist/

# OpenAPI spec → clean Markdown API docs
json2many convert openapi.json --to markdown --template openapi --output API.md

# Re-convert on every save while you iterate
json2many watch openapi.json --to markdown --template openapi --output API.md

---

Formats

Format	When to use	Options
markdown	Docs, wikis, changelogs	title, heading_offset, max_heading_level, bullet_lists, table_for_lists, frontmatter, code_block_keys, template (openapi)
xml	Legacy system integration, data exchange	root_element, item_element, pretty_print
csv	Spreadsheets, analyst handoff	delimiter, quotechar, include_header, columns
html	Stakeholder reports, CI build artifacts	title, table_style, wrap_in_page
jsonl	Log pipelines, ML fine-tuning, streaming	ensure_ascii
sql	Database seeding, fixture data for tests	table, include_create, batch_size

---

Project Config

Add .json2many.toml at your project root to share converter settings across a team:

[converters.csv]
delimiter = ";"

[converters.xml]
pretty_print = true
root_element = "records"

Explicit options always override the config file. See the User Guide for the full priority order and all supported keys.

---

Development

uv sync --extra cli --dev       # install runtime, CLI, and dev tooling
uv run pre-commit install       # install Git hooks
uv run pre-commit run --all-files
uv run pytest

The pre-commit setup runs Ruff lint fixes, Ruff formatting, YAML validation, trailing whitespace cleanup, and final newline checks. Ruff is pinned through both pyproject.toml and .pre-commit-config.yaml; keep those versions aligned when upgrading the formatter.

Maintainers: See RELEASING.md for the release process.

License

MIT — see LICENSE.