`nti.externalization.representation`: Reading and writing objects to strings

External representation support.

The provided implementations of IExternalObjectIO live here. We provide and register two, one for JSON and one for YAML.

class OrJsonRepresenter[source]

Default IO object using orjson for JSON input/output.

static dump(obj, fp=None, sort_keys=False, as_str=True) → str | bytes[source]: Given an object that is known to already be in an externalized form, convert it to JSON. This can be about 10% faster then requiring a pass across all the sub-objects of the object to check that they are in external form, while still handling a few corner cases with a second-pass conversion. (These things creep in during the object decorator phase and are usually links.)

Changed in version 3.0.0: Added the sort_keys parameter, defaulting to false for speed. Added the as_str parameter, defaulting to true for backwards compatibility. If set to false, then a bytes object will be returned (and written to any fp). Bytes is orjson’s native output format, meaning no encoding/decoding is required when this is false.

Other keyword arguments are ignored.

class StdJsonRepresenter[source]

Default IO object using json for JSON input/output.

static dump(obj, fp=None, sort_keys=False, as_str=True) → str | bytes[source]: Given an object that is known to already be in an externalized form, convert it to JSON. This can be about 10% faster then requiring a pass across all the sub-objects of the object to check that they are in external form, while still handling a few corner cases with a second-pass conversion. (These things creep in during the object decorator phase and are usually links.)

Changed in version 3.0.0: Added the sort_keys parameter, defaulting to false for speed. Added the as_str parameter, defaulting to true for backwards compatibility and speed. If set to false, then a bytes object will be returned (and written to any fp). Because str is the standard library’s default output format, this requires decoding.

Other keyword arguments are ignored.

WithRepr(default=<function _default_repr>)[source]

A class decorator factory to give a __repr__ to the object. Useful for persistent objects.

class YamlRepresenter[source]

Default IO object using yaml for object input/output.

static dump(obj, fp=None) → str[source]: Other keyword arguments are ignored.

to_external_representation(obj, ext_format='json', name=NotGiven, **repr_kwargs) → str | bytes[source]

Transforms (and returns) the obj into its external (string) representation.

Parameters:: ext_format (str) – One of EXT_REPR_JSON or EXT_REPR_YAML, or the name of some other utility that implements IExternalObjectRepresenter

The repr_kwargs are passed to the dump method of the representer.

Changed in version 3.0.0: Added repr_kwargs

Changed in version 3.1.0: Removed the deprecated ‘registry’ param

to_json_representation(obj) → str[source]: A convenience function that calls to_external_representation() with EXT_REPR_JSON.

to_json_representation_fast(obj) → bytes[source]

A convenience function that calls to_external_representation() with EXT_REPR_JSON and additional parameters to optimize for speed.

Note that this bypasses utility lookup and directly uses JsonRepresenter. It is also only fastest when using orjson.

Added in version 3.0.0.

Changed in version 3.1.0: Now properly externalizes the object instead of relying on the second-chance externalization mechanism.

to_json_representation_sorted(obj) → str[source]

Like to_json_representation, but guarantees that the keys are sorted. This is slower, but may be helpful in tests that do string comparisons.

Note that this bypasses utility lookup and directly uses JsonRepresenter

Added in version 3.1.0.

nti.externalization.representation: Reading and writing objects to strings