JSONC API Reference¶

def loads(
    text: str,
    *,
    cls: type[json.JSONDecoder] | None = None,
    object_hook: Any = None,
    parse_float: Any = None,
    parse_int: Any = None,
    parse_constant: Any = None,
    object_pairs_hook: Any = None,
    **kwargs: Any,
) -> Any:
    """Deserialize a JSONC string to a Python object.

    Strips ``//``, ``#``, and ``/* */`` comments and trailing commas before
    delegating to :func:`json.loads`.

    Args:
        text: JSONC source string.
        cls: Custom JSON decoder class.
        object_hook: Called with the result of any object literal decoded.
        parse_float: Called with every JSON float string decoded.
        parse_int: Called with every JSON int string decoded.
        parse_constant: Called with ``-Infinity``, ``Infinity``, ``NaN``.
        object_pairs_hook: Called with an ordered list of pairs.
        **kwargs: Additional keyword arguments passed to :func:`json.loads`.

    Returns:
        Deserialized Python object.

    Raises:
        JSONCDecodeError: If the text is not valid JSONC.
    """
    cleaned = _preprocess(text)
    try:
        return json.loads(
            cleaned,
            cls=cls,
            object_hook=object_hook,
            parse_float=parse_float,
            parse_int=parse_int,
            parse_constant=parse_constant,
            object_pairs_hook=object_pairs_hook,
            **kwargs,
        )
    except json.JSONDecodeError as exc:
        line, col = _remap_error_position(text, cleaned, exc.pos)
        raise JSONCDecodeError(exc.msg, text, exc.pos) from None

def load(
    fp: IO[str],
    *,
    cls: type[json.JSONDecoder] | None = None,
    object_hook: Any = None,
    parse_float: Any = None,
    parse_int: Any = None,
    parse_constant: Any = None,
    object_pairs_hook: Any = None,
    **kwargs: Any,
) -> Any:
    """Deserialize a JSONC file to a Python object.

    Args:
        fp: A text file-like object containing JSONC.
        cls: Custom JSON decoder class.
        object_hook: Called with the result of any object literal decoded.
        parse_float: Called with every JSON float string decoded.
        parse_int: Called with every JSON int string decoded.
        parse_constant: Called with ``-Infinity``, ``Infinity``, ``NaN``.
        object_pairs_hook: Called with an ordered list of pairs.
        **kwargs: Additional keyword arguments passed to :func:`json.loads`.

    Returns:
        Deserialized Python object.

    Raises:
        JSONCDecodeError: If the content is not valid JSONC.
    """
    return loads(
        fp.read(),
        cls=cls,
        object_hook=object_hook,
        parse_float=parse_float,
        parse_int=parse_int,
        parse_constant=parse_constant,
        object_pairs_hook=object_pairs_hook,
        **kwargs,
    )

def dumps(
    obj: Any,
    *,
    skipkeys: bool = False,
    ensure_ascii: bool = True,
    check_circular: bool = True,
    allow_nan: bool = True,
    cls: type[json.JSONEncoder] | None = None,
    indent: int | str | None = None,
    separators: tuple[str, str] | None = None,
    default: Any = None,
    sort_keys: bool = False,
    **kwargs: Any,
) -> str:
    """Serialize a Python object to a JSON string.

    This is a pass-through to :func:`json.dumps` for API compatibility.

    Args:
        obj: Python object to serialize.
        skipkeys: Skip keys that are not basic types.
        ensure_ascii: Escape non-ASCII characters.
        check_circular: Check for circular references.
        allow_nan: Allow ``NaN``, ``Infinity``, ``-Infinity``.
        cls: Custom JSON encoder class.
        indent: Indentation level for pretty-printing.
        separators: Item and key separators.
        default: Called for objects that are not serializable.
        sort_keys: Sort dictionary keys.
        **kwargs: Additional keyword arguments passed to :func:`json.dumps`.

    Returns:
        JSON string.
    """
    return json.dumps(
        obj,
        skipkeys=skipkeys,
        ensure_ascii=ensure_ascii,
        check_circular=check_circular,
        allow_nan=allow_nan,
        cls=cls,
        indent=indent,
        separators=separators,
        default=default,
        sort_keys=sort_keys,
        **kwargs,
    )

def dump(
    obj: Any,
    fp: IO[str],
    *,
    skipkeys: bool = False,
    ensure_ascii: bool = True,
    check_circular: bool = True,
    allow_nan: bool = True,
    cls: type[json.JSONEncoder] | None = None,
    indent: int | str | None = None,
    separators: tuple[str, str] | None = None,
    default: Any = None,
    sort_keys: bool = False,
    **kwargs: Any,
) -> None:
    """Serialize a Python object to a JSON file.

    This is a pass-through to :func:`json.dump` for API compatibility.

    Args:
        obj: Python object to serialize.
        fp: A text file-like object to write to.
        skipkeys: Skip keys that are not basic types.
        ensure_ascii: Escape non-ASCII characters.
        check_circular: Check for circular references.
        allow_nan: Allow ``NaN``, ``Infinity``, ``-Infinity``.
        cls: Custom JSON encoder class.
        indent: Indentation level for pretty-printing.
        separators: Item and key separators.
        default: Called for objects that are not serializable.
        sort_keys: Sort dictionary keys.
        **kwargs: Additional keyword arguments passed to :func:`json.dump`.
    """
    json.dump(
        obj,
        fp,
        skipkeys=skipkeys,
        ensure_ascii=ensure_ascii,
        check_circular=check_circular,
        allow_nan=allow_nan,
        cls=cls,
        indent=indent,
        separators=separators,
        default=default,
        sort_keys=sort_keys,
        **kwargs,
    )