Skip to main content

Simple Python-based JSON parser/indenter/formatter

Project description

json-indent

EditorConfig-enabled pre-commit-enabled Python-3.7+ CodeStyle-ruff pre-commit-hook-included

This is a simple Python-based tool for parsing/indenting/formatting JSON.

Python's json module actually contains such a tool; it's even simpler and is missing twiddles for specifying the amount of indent, whether to (re)compact, and whether to sort keys when parsing.

json-indent can be useful:

  • On the command-line
  • From within Vim or similar editors
  • As a pre-commit hook

(js-beautify is another such tool; it can parse JavaScript as well as JSON, but it has no built-in pre-commit hook).

Contents

Requirements

  • A Python interpreter, version 3.7 or later (version 2.7 support is deprecated, but may still work)

Installing

It is recommended to install json-indent either:

To install with uv:

uv tool install json-indent

How to Use

For a summary of all the available options:

uv tool run json-indent --help

Or, with the uvx shortcut:

uvx json-indent --help

Or, if you prefer to call the script directly:

/path/to/json-indent --help

[!TIP]

There are a number of different ways to run tools that are delivered as Python modules. For the remainder of this document, we will use uvx json-indent to mean whichever one you prefer for your Python installation and operating environment.

See How to Run Your Python Scripts for more details.

Quickstart

To read JSON from a file, parse it, and write it to the standard output:

uvx json-indent input.json

To write to a file instead:

uvx json-indent -o output.json input.json

To read from the standard input, you can use - as the filename:

uvx json-indent -o - -

Or simply:

uvx json-indent

To modify a file in place:

uvx json-indent --inplace input.json

To display json-indent's version:

uvx json-indent --version

See the command-line help for more options, including:

  • Indent size
  • "Compact" mode
  • Key sorting

Command-line Autocompletion

json-indent provides command-line autocompletion for the Bash command-line shell and compatible shells, using the argcomplete Python package.

For instructions on how to enable completion:

uvx json-indent --completion-help

Advanced Topics

Pre-Commit Hook

json-indent has support for the pre-commit framework for running tools before committing to your git project. The hook will:

  1. Parse your JSON files and emit messages about any errors it encounters.
  2. Format and indent your JSON files according to the --indent, --compact, and --sort-keys options you supply (or their default values if you don't supply one).

To add a hook for json-indent to your project, use the following YAML in your project's .pre-commit-config.yaml:

  - repo: https://github.com/jmknoble/json-indent
    rev: v2.4.0
    hooks:
      - id: json-indent

[!NOTE]

HOW IT WORKS:

Under the hood this uses a .pre-commit-hooks.yaml file in the root of the Git project to define the parameters of the pre-commit hook.

Key info:

  • json-indent must accept multiple input files on the command line.
  • The --inplace option is needed in order to automatically indent JSON source files.

Integration with Vim

You can use json-indent from within Vim to format JSON directly in your editing session.

To enable this functionality, you can add the following to your vimrc file:

""""""""""""""""""""""""""""""""""""""""
" JSON parsing/indenting
" https://github.com/jmknoble/json-indent
"
" Normal mode
"
" Compact JSON stanza starting at current character (uses '%' to move to matching brace)
nmap <Leader>jc :%!json-indent -c
nmap <Leader>JC <Leader>jc
"
" Parse/indent JSON stanza contained in current line
nmap <Leader>jp 0!$json-indent<CR>j
nmap <Leader>JP <Leader>jp
"
" Parse/indent JSON stanza contained in current line with sorted keys
nmap <Leader>js 0!$json-indent -s<CR>j
nmap <Leader>JS <Leader>js
"
" Visual mode
"
" Compact JSON stanza contained in current selection
vmap <Leader>jc !json-indent -c<CR>j
vmap <Leader>JC <Leader>jc
"
" Parse/indent JSON stanza contained in current selection
vmap <Leader>jp !json-indent
vmap <Leader>JP <Leader>jp
"
" Parse/indent JSON stanza contained in current selection with sorted keys
vmap <Leader>js !json-indent -s<CR>j
vmap <Leader>JS <Leader>js
""""""""""""""""""""""""""""""""""""""""

[!TIP]

This uses the !command feature to run an external command as a filter.

Use the Vim command :help mapleader (or see mapleader) for an explanation of <Leader>.

Developing json-indent

See DEVELOPING.

References

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

json_indent-2.7.2.tar.gz (33.0 kB view hashes)

Uploaded Source

Built Distribution

json_indent-2.7.2-py3-none-any.whl (15.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page