Module Reference

Convert dict, list, or tuple to Object.

class jsify.simplify.SimplifiedEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: JSONEncoder

JSON encoder for structures containing SimplifiedObject and Undefined.

This encoder customizes JSON serialization for types relevant to the simplified object pattern:

  • The Undefined singleton is encoded as null in JSON.

  • Any instance of SimplifiedObject is serialized as a JSON object using its internal attribute dictionary.

  • Other types are handled by the standard JSONEncoder.

This allows Python objects using this pattern to be safely and predictably encoded to JSON for interoperability or storage.

Parameters:

  • skipkeys (bool, optional) – Skip keys not of a basic type if True.

  • ensure_ascii (bool, optional) – Escape all non-ASCII characters if True.

  • check_circular (bool, optional) – Check for circular references if True.

  • allow_nan (bool, optional) – Allow NaN and Infinity values if True.

  • sort_keys (bool, optional) – Sort output dictionary keys if True.

  • indent (int or str, optional) – Indentation level for pretty-printing.

default(obj)[source]

Return a serializable form of SimplifiedObject or Undefined.

  • If obj is Undefined, return None (serialized as null in JSON).

  • If obj is a SimplifiedObject, serialize using its __dict__.

  • Otherwise, use the standard JSONEncoder behavior.

Parameters:

obj (Any) – The object to serialize.

Returns:

JSON-serializable representation of obj.

Return type:

Any

class jsify.simplify.SimplifiedObject(mapping_or_iterable=(), /, **kwargs)[source]

Bases: SimpleNamespace

An extension of SimpleNamespace that mimics JavaScript-like property access.

This class behaves like a dynamic object whose attributes can be set and retrieved. If an attribute is accessed that does not exist, it returns the singleton Undefined object instead of raising an AttributeError. This enables safe chaining of attribute access in deeply nested structures, similar to how missing properties return undefined in JavaScript.

When a dictionary is deserialized into a SimplifiedObject, its keys become attributes. Any missing attribute will yield Undefined.

<dynamic>

All fields are dynamically set as attributes. Missing fields yield Undefined.

Type:

Any

See also

jsify.cjsify.Undefined

The singleton returned for missing attributes.

jsify.simplify.load_simplified(fp, *args, **kwargs)[source]

Load JSON from a file and produce a structure of SimplifiedObject instances.

This function behaves like json.load, but ensures that every dictionary in the resulting object tree is converted to a SimplifiedObject. Attribute access is available throughout, and missing attributes yield Undefined.

Parameters:

  • fp (IO[str]) – File or file-like object to read JSON from.

  • *args – Additional positional arguments to json.load.

  • **kwargs – Additional keyword arguments to json.load.

Returns:

The parsed and converted JSON object structure.

Return type:

Any

jsify.simplify.loads_simplified(s, *args, **kwargs)[source]

Load JSON from a string and produce a structure of SimplifiedObject instances.

This function behaves like json.loads, but ensures that every dictionary in the resulting object tree is converted to a SimplifiedObject. All fields are accessible as attributes, and missing fields yield Undefined.

Parameters:

  • s (str) – JSON string to parse.

  • *args – Additional positional arguments to json.loads.

  • **kwargs – Additional keyword arguments to json.loads.

Returns:

The parsed and converted JSON object structure.

Return type:

Any

jsify.simplify.object_hook_convert_to_simple(obj)[source]

Object hook for JSON deserialization to convert dicts to SimplifiedObject.

When used as the object_hook in json.load or json.loads, this function replaces every dictionary with a SimplifiedObject, so that all fields can be accessed as attributes and any missing attribute access will yield Undefined.

Parameters:

obj (dict) – The dictionary object parsed from JSON.

Returns:

The dictionary converted to a SimplifiedObject.

Return type:

SimplifiedObject

jsify.simplify.simplified_dump(fp, obj, **kwargs)[source]

Serialize an object as JSON and write it to a file using SimplifiedEncoder.

This function writes the JSON serialization of an object to a file or file-like object, using the same rules as simplified_dumps. It handles Undefined as null and serializes SimplifiedObject instances as objects.

Parameters:

  • fp (IO[str]) – File or file-like object to write the JSON output to.

  • obj (Any) – The object to serialize.

  • **kwargs – Any additional keyword arguments for json.dump.

Return type:

None

jsify.simplify.simplified_dumps(obj, **kwargs)[source]

Serialize an object as a JSON string using the SimplifiedEncoder.

This function provides JSON serialization for objects that may contain SimplifiedObject and Undefined values. The encoder ensures that Undefined is represented as null and all SimplifiedObject instances are serialized as JSON objects. Additional keyword arguments are passed to json.dumps.

Parameters:

  • obj (Any) – The object to serialize to JSON.

  • **kwargs – Any additional keyword arguments for json.dumps.

Returns:

JSON-formatted string representing the object.

Return type:

str

class jsify.json.ObjectEncoder(omit_undefined=True, *args, **kwargs)[source]

Bases: JSONEncoder

Custom JSON encoder supporting jsify objects, omitting Undefined values.

This encoder serializes:

  • Undefined as null in JSON, unless omitted.

  • Object (from jsify) by recursively converting them to plain Python objects using unjsify.

  • SimpleNamespace as a dictionary of its attributes.

  • All other types using standard JSON encoding.

The omit_undefined parameter controls whether fields or items with Undefined values are included in the output. If omit_undefined is True, all such values are omitted from dictionaries, lists, and tuples at all nesting levels before encoding.

Parameters:

  • omit_undefined (bool, optional) – If True, any field/item with value Undefined is omitted from the output (default: True).

  • *args – Additional positional arguments passed to json.JSONEncoder.

  • **kwargs – Additional keyword arguments passed to json.JSONEncoder.

default(o)[source]

Custom default handler for objects not serializable by default.

Parameters:

o (Any) – The object to encode.

Returns:

A JSON-serializable value.

Return type:

Any

Notes

  • Returns None for Undefined (serialized as null in JSON).

  • Returns unjsified value for Object instances.

  • Serializes SimpleNamespace as its attribute dictionary.

  • Falls back to the base encoder otherwise.

iterencode(o, _one_shot=False)[source]

Recursively remove all Undefined values (if enabled) before serialization.

Parameters:

  • o (Any) – The object to encode.

  • _one_shot (bool, optional) – Passed through to the base class.

Returns:

An iterator yielding encoded JSON chunks.

Return type:

generator

Notes

  • Converts all Object instances to plain Python objects using unjsify.

  • Omits fields/items with Undefined values if omit_undefined is True.

  • Handles all nested containers recursively.

jsify.json.jsified_dump(o, *args, omit_undefined=True, **kwargs)[source]

Serialize an object as JSON and write it to a file using ObjectEncoder.

Handles jsified objects and omits Undefined values if specified. All nested structures are unjsified recursively and can be filtered.

Parameters:

  • o (Any) – The object to serialize.

  • *args – Additional positional arguments passed to json.dump.

  • omit_undefined (bool, optional) – Whether to omit Undefined values (default: True).

  • **kwargs – Additional keyword arguments passed to json.dump.

Return type:

None

jsify.json.jsified_dumps(o, *args, omit_undefined=True, **kwargs)[source]

Serialize an object as a JSON string using ObjectEncoder.

Handles jsified objects and omits Undefined values if specified. All nested structures are unjsified recursively and can be filtered.

Parameters:

  • o (Any) – The object to serialize.

  • *args – Additional positional arguments passed to json.dumps.

  • omit_undefined (bool, optional) – Whether to omit Undefined values (default: True).

  • **kwargs – Additional keyword arguments passed to json.dumps.

Returns:

The JSON-formatted string.

Return type:

str