Public API

Overview

The main component is jsonstreams.Stream, which provides the interface for either an array or an object. The interfaces for this class depend on whether it was initialized as an array or an object.

Exceptions

exception JsonStreamsError(message)

A base exception class for other JSONstreams errors.

Parameters:

message (str (python 3) or unicode (python 2)) – the message to be displayed with the exception is raised

exception ModifyWrongStreamError(message)

An exception raised when trying to modify on object within the stream which is not in focus.

Because JSON is so strictly defined, and this module writes out all data into the stream immediately without building any intermediate data structures, it is impossible to write into a parent while a sub-stream is opened. This exception will be raised in that case.

It is not advised to handle this exception, it is almost certainly a programming error.

Parameters:

message (str) – the message to be displayed with the exception is raised

with jsonstreams.Stream(Type.OBJECT, filename='foo') as s:
    with s.subobject('bar') as b:
        s.write('foo', 'bar')
ModifyWrongStreamError
exception InvalidTypeError(message)

An exception that is raised when an invalid type is passed for an argument. Primarily this will be raised from the Object.write() and Object.iterwrite() methods.

JSON is pretty particularly about what kinds of values can be used as keys for objects, only text type is allowed, not lists, objects, null or numeric types. JSONstreams does not attempt to coerce values for the developer, instead it raises this exception.

It is not advised to handle this exception, it is almost certainly a programming error.

Parameters:

message (str (python 3) or unicode (python 2)) – the message to be displayed with the exception is raised

with jsonstreams.Stream(Type.OBJECT, filename='foo') as s:
    with s.subobject(1) as b:
InvalidTypeError
exception StreamClosedError(message)

An exception that is raised when trying to write into an Object or Array after the close() method has already been called.

Parameters:

message (str (python 3) or unicode (python 2)) – the message to be displayed with the exception is raised

with jsonstreams.Stream(Type.OBJECT, filename='foo') as s:
    with s.subobject(1) as b:
        b.write('foo', 'bar)
    b.write('foo', 'bar)
StreamClosedError

Classes

class Type

This is an enum that provides valid types for the Stream class.

OBJECT

A JSON object

ARRAY

A JSON array

object

Deprecated since version 0.6: Use the OBJECT attribute instead.

A JSON object

array

Deprecated since version 0.6: Use the ARRAY attribute instead.

A JSON array

class Stream(jtype, filename=none, fd=none, indent=0, pretty=false, encoder=json.JSONencoder)

The stream class is the basic entry point for using JSONstreams, and is the only class meant to be instantiated directly. When initialized this class will add the methods of Object or Array, as matches the value of jtype.

It can be initialized with either a filename, which it will open via open(), or a file-like object already opened for write, but not both. If it is passed a file-like object it will no longer close that object, it is the caller’s job to do so.

It also takes and indent argument, which will cause the writer to add the appropriate white space to the output. For especially large documents this may help decode, as some parsers have a limit on the number of characters per line.

A pretty flag can be passed, which will further cause indents to be consistently written even for complex objects, which would normally not be set at the same base indent level as other objects. This can have a negative effect on performance.

This class can also be used as a context manager (used with the with statement), which will automatically call the Stream.close() method when exiting the context.

with jsonwriter.Stream(jsonstreams.Type.ARRAY, filename='foo') as s:
    s.write('foo')

Note

If the stream opens the file-like object itself by filename it will always close the file when the Stream is closed.

Warning

The behavior of close_fd will change in the future. Currently it defaults to True, but in JsonStreams 1.0 it will default to False.

Parameters:

  • jtype (Type) – A value of the Type enum.

  • filename (str or None) – If set this will be opened and the stream written into it.

  • fd (file) – A file-like object defining a write and close method.

  • indent (int) – The number of spaces before each level in the JSON document.

  • pretty (bool) – Whether or not to indent complex objects.

  • encoder (json.JSONEncoder) – A callable that will create a json.JSONEncoder instance.

  • close_fd (bool) – Close the fd when the Stream closes. Ignored if passed a filename

write()

This method will differ in signature depending on whether jtype is Type.ARRAY or Type.OBJECT.

If Type.ARRAY then this method is an alias for Array.write(). If Type.’object then this method is an alias for Object.write().

iterwrite()

This method will differ in signature depending on whether jtype is Type.OBJECT or Type.ARRAY.

If Type.ARRAY then this method is an alias for Array.iterwrite(). If Type.OBJECT then this method is an alias for Object.iterwrite().

close()

This method will close the root object by calling either Object.close() or Array.close(), and will also close the file.

subobject()

This method will differ in signature depending on whether jtype is Type.OBJECT or Type.ARRAY.

This method will open a new object in the stream by calling either Object.subobject() or Array.subobject()

subarray()

This method will differ in signature depending on whether jtype is Type.OBJECT or Type.ARRAY.

This method will open a new array in the stream by calling either Object.subarray() or Array.subarray()

class Object

The Object constructor is not considered a public API, and is not documented here because it is not guaranteed according to the Semantic Versioning standard. All other public methods, however are considered public API.

This class represents an object in a JSON document. It provides as public API all of the methods necessary to write into the stream and to close it. Like the Stream it provides a context manager, and can be used as a context manager, including when called from the Object.subobject() or Array.subobject().

subobject(key)

Open a new sub-object within the current object stream.

Parameters:

key (str) – When written this will be the key and the new object will be the value

Returns:

The sub-object instance.

Return type:

Object

Raises:
subarray(key)

Open a new sub-array within the current object stream.

Parameters:

key (str) – When written this will be the key and the new Array will be the value

Returns:

The sub-array instance.

Return type:

Array

Raises:
write(key, value)

Write a key:value pair into the object stream.

Parameters:

  • key (str) – The key value.

  • value (Any type that can be encoded by the encoder argument of Stream) – The value to be written.

Raises:
iterwrite(args)

Write key:value pairs from an iterable.

One should not use this for dumping a complete dictionary or list, unless doing transformations. This is intended to have a generator passed into it.

with jsonstreams.Stream(Type.OBJECT, filename='foo') as s:
    s.iterwrite((str(s), s) for s in range(5))
param args:

An iterator returning key value pairs

type value:

An iterable of tuples where the key is str and the value is any type that can be encoded by the encoder argument of Stream

raises InvalidTypeError:

If the key is not str

raises ModifyWrongStreamError:

if this stream is not the top of the stack

raises StreamClosedError:

if Object.close() has been called

close()

Close the current object.

Once this is called any call to write(), iterwrite(), subobject(), or subarray() will cause an StreamClosedError to be raised.

class Array

The Array constructor is not considered a public API, and is not documented here because it is not guaranteed according to the Semantic Versioning standard. All other public methods are considered public API.

This class represents an array in a JSON document. It provides as public API all of the methods necessary to write into the stream and to close it. Like the Stream it provides a context manager, and can be used as a context manager, including when called from the Object.subarray() or Array.subarray().

subobject()

Open a new sub-object within the current array stream.

Returns:

The sub-object instance.

Return type:

Object

Raises:
subarray()

Open a new sub-array within the current array stream.

Returns:

The sub-array instance.

Return type:

Array

Raises:
write(value)

Write a value into the array stream.

Parameters:

value (Any type that can be encoded by the encoder argument of Stream) – The value to be written.

Raises:
iterwrite(args)

Write values into an array from an iterator.

One should not use this for dumping a complete list unless doing transformations. This is intended to have a generator passed into it.

with jsonstreams.Stream(Type.OBJECT, filename='foo') as s:
    s.iterwrite(range(10, step=2))
param args:

An iterator returning key value pairs

type value:

An iterable of tuples where the key is str and the value is any type that can be encoded by the encoder argument of Stream

raises ModifyWrongStreamError:

if this stream is not the top of the stack

raises StreamClosedError:

if Object.close() has been called

close()

Close the current object.

Once this is called any call to write(), iterwrite(), subobject(), or subarray() will cause an StreamClosedError to be raised.