===============
 json_delta.py
===============

.. automodule:: json_delta

Main entry points
-----------------

.. autofunction:: json_delta.diff

.. autofunction:: json_delta.patch

.. autofunction:: json_delta.udiff

.. autofunction:: json_delta.upatch

Utility functions
-----------------

.. autofunction:: json_delta.compact_json_dumps

.. autofunction:: json_delta.all_paths

.. autofunction:: json_delta.follow_path

.. autofunction:: json_delta.in_one_level

.. autofunction:: json_delta.check_diff_structure

Functions for computing normal diffs.
-------------------------------------

.. autofunction:: json_delta.commonality

.. autofunction:: json_delta.compute_keysets

.. autofunction:: json_delta.keyset_diff

.. autofunction:: json_delta.needle_penalty

.. autofunction:: json_delta.needle_diff

.. autofunction:: json_delta.this_level_diff

.. autofunction:: json_delta.split_deletions

.. autofunction:: json_delta.sort_stanzas

Functions for applying normal patches
-------------------------------------

.. autofunction:: json_delta.patch_stanza

Functions for computing udiffs.
-------------------------------

The data structure representing a udiff that these functions all
manipulate is a pair of lists of iterators ``(left_lines,
right_lines)``.  These lists are expected (principally by
:py:func:`generate_udiff_lines()`, which processes them), to be of the
same length.  A pair of iterators ``(left_lines[i], right_lines[i])``
may yield exactly the same sequence of output lines, each with ``' '``
as the first character (representing parts of the structure the input
and output have in common).  Alternatively, they may each yield zero
or more lines (referring to parts of the structure that are unique to
the inputs they represent).  In this case, all lines yielded by
``left_lines[i]`` should begin with ``'-'``, and all lines yielded by
``right_lines[i]`` should begin with ``'+'``.
 
.. autofunction:: json_delta.patch_bands

.. autofunction:: json_delta.single_patch_band

.. autofunction:: json_delta.commafy

.. autofunction:: json_delta.add_matter

.. autofunction:: json_delta.udiff_dict

.. autofunction:: json_delta.reconstruct_alignment

.. autofunction:: json_delta.udiff_list

.. autofunction:: json_delta.generate_udiff_lines

Functions for applying udiffs as patches.
-----------------------------------------

.. autofunction:: json_delta.extended_json_decoder

.. autofunction:: json_delta.fill_in_ellipses

.. autofunction:: json_delta.split_udiff_parts

Basic script functionality
--------------------------

json_delta.py can be run as a script.  The usage syntax is
``json_delta.py (diff | patch) [-u]``, and the script then runs as a
filter: standard input is expected to read as a JSON structure
``[<arg1>, <arg2>]``.  The two arguments are fed to one of the
functions :func:`diff`, :func:`patch`, :func:`udiff` or
:func:`upatch`, as appropriate from the command-line arguments, and
the result is written to standard output.

The package available from pypi also installs the scripts
`json_diff <json_diff.1>` and `json_patch <json_patch.1>`,
which make available a more versatile and useful command-line
interface to :mod:`json_delta`.  Their manpages are included in this
documentation.
