CLI Entry Point for jsoncsv: How the Command-Line Interface Works

The CLI entry point for jsoncsv is the jsoncsv function located in jsoncsv/main.py, registered as a console script in pyproject.toml under the [project.scripts] section.

The jsoncsv tool, maintained in the alingse/jsoncsv repository, provides bidirectional conversion between JSON and CSV formats through a command-line interface. Understanding the CLI entry point helps developers extend the tool, debug issues, or invoke it programmatically from other Python scripts.

Where the CLI Entry Point Is Defined

The primary entry point resides in the jsoncsv function inside jsoncsv/main.py. This function is decorated with Click commands and options to handle argument parsing.

When you install the package via pip, the executable is created through the following declaration in pyproject.toml:

[project.scripts]
jsoncsv = "jsoncsv.main:jsoncsv"
mkexcel = "jsoncsv.main:mkexcel"

This configuration tells the package installer to generate a jsoncsv executable that points directly to the jsoncsv function in the jsoncsv.main module. The same file also contains a secondary entry point mkexcel for Excel format output.

How the Entry Point Works Internally

The jsoncsv function uses the Click library to build the command-line interface. The workflow follows these steps:

1. Click decorators (@click.command() and @click.option) parse command-line flags including --sep, --safe, --expand, --restore, and -A for array handling.
2. Based on the --expand or --restore flags, the function selects the appropriate transformation function (expand_fn or restore_fn) from jsoncsv.jsontool.
3. The function calls convert_json with the selected transformation, separator, safety mode, and array settings.
4. Input and output streams are properly closed after conversion.

The heavy lifting is delegated to utilities in jsoncsv/jsontool.py, specifically convert_json, expand, and restore, while jsoncsv/main.py focuses purely on CLI argument handling and orchestration.

Using the jsoncsv CLI

Basic Command-Line Usage

After installation, you can invoke the tool directly using the jsoncsv command:

# Expand JSON to CSV (default mode)

jsoncsv input.json output.csv

# Use custom separator (default is dot)

jsoncsv -s "_" data.json data.csv

# Restore previously expanded JSON

jsoncsv --restore expanded.json restored.json

# Enable safe mode (fails on non-JSON values)

jsoncsv --safe input.json output.csv

# Process JSON arrays

jsoncsv -A array.json array.csv

Programmatic Invocation

You can also invoke the same entry point from Python code using Click's testing utilities or by importing the function directly:

from jsoncsv.main import jsoncsv
from click.testing import CliRunner

runner = CliRunner()
result = runner.invoke(jsoncsv, ['examples/sample.json', '-'])
print(result.output)   # CSV output written to stdout

This approach is useful for testing, automation scripts, or integrating jsoncsv functionality into larger applications without shelling out to the command line.

Summary

• The CLI entry point for jsoncsv is the jsoncsv function in jsoncsv/main.py, registered via pyproject.toml.
• The entry point is declared in the [project.scripts] section as jsoncsv = "jsoncsv.main:jsoncsv".
• Click powers the argument parsing and help generation.
• The function delegates processing to jsoncsv.jsontool.convert_json and related utilities.
• You can invoke the CLI programmatically using CliRunner or import the function directly for testing.

Frequently Asked Questions

What file contains the jsoncsv CLI entry point?

The CLI entry point is defined in jsoncsv/main.py. This file contains the jsoncsv function that serves as the main command handler and is registered as the console script entry point in pyproject.toml.

How is the jsoncsv command registered for installation?

The command is registered in pyproject.toml under the [project.scripts] section with the line jsoncsv = "jsoncsv.main:jsoncsv". This creates the jsoncsv executable when you install the package via pip.

Can I call the jsoncsv CLI entry point from Python code?

Yes. You can import the jsoncsv function directly from jsoncsv.main and invoke it using Click's CliRunner for testing, or call it with appropriate arguments. This allows programmatic access without spawning a subprocess.

What library powers the jsoncsv command-line interface?

The CLI uses the Click library to define commands, options, and help text. Click handles the parsing of flags like --expand, --restore, and --safe, then passes the processed arguments to the conversion logic in jsoncsv/jsontool.py.

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