- ak.to_json(array, file=None, *, line_delimited=False, num_indent_spaces=None, num_readability_spaces=0, nan_string=None, posinf_string=None, neginf_string=None, complex_record_fields=None, convert_bytes=None, convert_other=None)#
array – Array-like data (anything
file (None, str/pathlib.Path, or file-like object) – If None, this function returns JSON-encoded bytes. Otherwise, this function has no return value. If a string/pathlib.Path, this function opens a file with that name, writes JSON data, and closes the file. If that path has a URI protocol (like “https://” or “s3://”), this function attempts to open the file with the fsspec library. If a file-like object with a
writemethod, this function writes to the object, but does not close it.
line_delimited (bool or str) – If False, a single JSON document is written, representing the entire array or record. If True, each element of the array (or just the one record) is written on a separate line of text, separated by
"\n". If a string, such as
"\r\n", it is taken as a custom line delimiter. (Use
os.linesepfor a platform-dependent line delimiter.)
num_indent_spaces (None or nonnegative int) – Number of spaces to indent nested elements, for pretty-printed JSON. If None, the JSON output is written on one line of text. Ignored if
line_delimitedis True or a string.
num_readability_spaces (nonnegative int) – Number of spaces to include after commas (
,) and colons (
:), for pretty-printed JSON.
nan_string (None or str) – If not None, floating-point NaN values will be replaced with this string instead of a JSON number.
posinf_string (None or str) – If not None, floating-point positive infinity values will be replaced with this string instead of a JSON number.
neginf_string (None or str) – If not None, floating-point negative infinity values will be replaced with this string instead of a JSON number.
convert_bytes (None or function) – If not None, this function is applied to all Python 3 bytes objects to produce something JSON serializable, such as a string using UTF-8 or Base64 encoding, lists of integers, etc.
convert_other (None or function) – Passed to
defaultto convert any other objects that
ak.to_listwould return but are not JSON serializable.
array (many types supported, including all Awkward Arrays and
Records) into JSON text. Returns bytes (encoded JSON) if
file is None;
otherwise, this function returns nothing and writes to a file.
This function converts the array into Python objects with
some conversions to make the data JSON serializable (
convert_other), then uses
json.dumps to return a string or
to write to a file (depending on the value of
line_delimited is True or a line-delimiter string like
the output is line-delimited JSON, variously referred to as “ldjson”, “ndjson”, and
“jsonl”. (Use an appropriate file extension!)
To pretty-print the JSON, set
num_indent_spaces=4, num_readability_spaces=1 (for
Awkward Array types have the following JSON translations.
ak.types.OptionType: missing values are converted into None.
ak.types.ListType: converted into JSON lists.
ak.types.RegularType: also converted into JSON lists. JSON (and Python) forms lose information about the regularity of list lengths.
ak.types.RecordTypewithout field names: converted into JSON objects with numbers as strings for keys.
ak.types.RecordTypewith field names: converted into JSON objects.
ak.types.UnionType: JSON data are naturally heterogeneous.
If the array contains any NaN (not a number), infinite values, or
_must_ be supplied.
If the array contains any raw bytestrings (
"__array__" equal to
convert_bytes _must_ be supplied. To interpret as strings, use
To Base64-encode, use
lambda x: base64.b64encode(x).decode().
Other non-serializable types are only possible through custom behaviors that
__getitem__ (which might return arbitrary Python objects). Use
convert_other to detect these types and convert them.