Simple Python-based JSON parser/indenter/formatter
Project description
json-indent
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
- Installing
- How to Use
- Command-line Autocompletion
- Advanced Topics
- Developing json-indent
- References
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:
- In its own virtual environment (for example, using uv), or
- As a pre-commit hook
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:
- Parse your JSON files and emit messages about any errors it encounters.
- 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
- Python:
- How to Run Your Python Scripts
- argcomplete on PyPI and GitHub
- pre-commit
- Vim:
- js-beautify
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for json_indent-2.7.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0b8f1c39de3c139cb83c29bb0a5304606a429603fc16f34c5232f108b7af5adb |
|
MD5 | 20778c4760964aa0b8fd20a3244274f4 |
|
BLAKE2b-256 | 700217eea729b98396e34b8806bf44ca4b2c2e4ec3eeb269b47269b1d187eca4 |