jsoncsv Commands: Expand, Restore, and Convert JSON from the Command Line

The jsoncsv Python package provides two main command-line utilities—jsoncsv for flattening and restoring nested JSON structures, and mkexcel for converting JSON streams to CSV or Excel formats.

The alingse/jsoncsv repository delivers a lightweight toolkit for JSON data transformation directly from your shell. Understanding these core jsoncsv commands enables data engineers to flatten complex hierarchies and export to spreadsheets without writing custom conversion scripts.

Overview of Main jsoncsv Commands

The package registers two console scripts via entry points defined in pyproject.toml (lines 44-47). These wrap the underlying Python library in a Click-based CLI for seamless shell integration.

The jsoncsv Command (Expand and Restore)

Implemented in jsoncsv/main.py (lines 24-55), this command handles bidirectional transformation of JSON documents. It imports conversion logic from jsoncsv/jsontool.py to either flatten nested objects or restore them to original hierarchies.

Key capabilities:

• Expand mode (-e, --expand): Flattens nested structures using dot notation (default separator .)
• Restore mode (-r, --restore): Rebuilds original JSON from flattened key-value maps
• Safe encoding (--safe): Handles keys containing the separator character to prevent collision
• Array handling (--array): Configures processing of JSON arrays during expansion

The mkexcel Command (CSV and XLS Export)

Defined in jsoncsv/main.py (lines 55-94), this command streams JSON input into spreadsheet formats. It delegates to dumper classes in jsoncsv/dumptool.py for format-specific output generation.

Key capabilities:

• Format selection (-t, --type): Specify csv or xls output format
• Header sorting (-s, --sort): Alphabetize column headers in the output
• Row inference (--row): Pre-read specified number of rows to determine column ordering

Technical Implementation of jsoncsv Commands

How jsoncsv Transforms JSON Structures

When invoked with --expand, the command calls convert_json() from jsoncsv/jsontool.py, which executes the expand() function (lines 93-124). This implementation walks the JSON tree using gen_leaf to generate flattened keys with configurable separators. The restore() function reverses this operation by splitting keys and rebuilding nested structures via from_leaf, supporting safe-key decoding when the --safe flag is used.

How mkexcel Generates Spreadsheets

The command instantiates either DumpCSV or DumpXLS classes from jsoncsv/dumptool.py based on the --type parameter. It processes JSON streams to build two-dimensional tables mapping headers to values, then writes either text-based CSV or binary XLS workbooks to the specified output destination.

Command-Line Usage Examples

Flattening Nested JSON with jsoncsv

# Expand a JSON file using default dot separator

jsoncsv -e input.json > flat.json

# Use custom separator with safe key encoding for complex keys

jsoncsv -e --sep '/' --safe input.json > flat_safe.json

Restoring Original Hierarchy

# Rebuild nested structure from flattened file

jsoncsv -r flat.json > restored.json

Converting to CSV and Excel with mkexcel

# Convert JSON stream to CSV

mkexcel -t csv input.json output.csv

# Create Excel file with sorted headers, pre-reading 2 rows for inference

mkexcel -t xls -s --row 2 input.json output.xls

Summary

• Two primary commands: jsoncsv for structural transformations (expand/restore) and mkexcel for format conversion (CSV/XLS)
• Entry point registration: Defined in pyproject.toml as jsoncsv.main:jsoncsv and jsoncsv.main:mkexcel
• Core implementation: jsoncsv/jsontool.py handles JSON tree manipulation; jsoncsv/dumptool.py handles spreadsheet generation
• CLI framework: Built on Click with support for stdin/stdout streaming, custom separators, and safe-key encoding

Frequently Asked Questions

What is the difference between the jsoncsv and mkexcel commands?

The jsoncsv command modifies JSON structure by expanding nested objects into flat key-value pairs or restoring flattened documents back to hierarchies, while mkexcel converts JSON into tabular spreadsheet formats without altering the internal data structure.

How does jsoncsv handle keys containing the separator character?

Use the --safe flag when expanding to encode keys that contain the separator (default .), then use the same flag during restoration to decode them properly. This prevents the tool from interpreting embedded dots as hierarchy delimiters.

Can jsoncsv process JSON arrays for Excel conversion?

Yes, the mkexcel command handles JSON streams containing arrays or objects, flattening them into rows. Use the --row parameter to pre-read rows for improved header inference when processing heterogeneous data structures.

Where are the command-line entry points defined in the source code?

The console scripts are registered in pyproject.toml under [project.scripts], mapping the jsoncsv command to jsoncsv.main:jsoncsv and mkexcel to jsoncsv.main:mkexcel. The Click command definitions and argument parsing logic reside in jsoncsv/main.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}