luxem Python Documentation

Click here for information about the luxem format.

An interface similar to Python's json module is provided with functions load, loads, dump and dumps. Reader and Writer provide the core functionality.

Table of contents:

Example

import luxem

tree = luxem.loads(b'{a: 1, b: (int) 2}')[0]
print(tree['b'].name)
> 'int'
print(tree['b'].value)
> '2'

data = luxem.dumps({'a': [1, 2, 3], 'b': luxem.Typed('int', 4)}, pretty=True)
print(data)
> {
>  	a: [
>  		1,
>  		2,
>  		3,
>  	],
>  	b: (int) 4,
> },

Installation

Install with `pip install luxem`. You'll need `gcc` and `python3-dev` to compile the underlying C code.

API

Functions

luxem.load(file)

luxem.loads(bytes)

Deserializes a document and returns an array of root values. Any typed values in the document will be converted to Typed.

luxem.dump(file, value, **kwargs)

luxem.dumps(value, **kwargs)

Serializes a single root element with Writer. kwargs are passed to the constructor. In dumps the serialized data is returned. To serialize multiple root elements you may call this function multiple times or use the Writer class directly.

luxem.to_ascii16(value)

luxem.from_ascii16(value)

Serializes and deserializes ascii16 data. ascii16 is a binary encoding using only the letters abcdefghijklmnop.

luxem.Typed

This represents an explicitly typed value.

luxem.Typed(name, value=None)

Creates a typed value with type attribute name and wrapped value attribute value.

luxem.Reader

Reader(object_begin, object_end, array_begin, array_end, key, type, primitive)

Constructs a Reader and initializes its read callbacks. All callbacks must be provided.

object_begin, object_end, array_begin, and array_end take a callback in the format:

def callback():
	return

key, type and primitive take a callback that accepts one string argument, in the format:

def callback(value):
	return

If any callback raises an exception, parsing stops and the exception is propagated up to the feed call.

feed(data, finish=True)

data must either be bytes or a binary file.

If data is a string

Parses the byte-string provided as the first parameter and returns the number of characters from the string that were consumed. If parsing multiple chunks, any unconsumed characters of the byte-string must be provided again, at the beginning of the next fed string.

If finish is True, will conclude the last state encountered while parsing if possible. Set finish to true if no more data is available.

If data is a file

Reads and parses the entire file passed as the first argument. finish is ignored.

luxem.Writer

Writer(target=None, pretty=False, use_spaces=False, indent_multiple=1)

All arguments are optional.

If target is None all data will be written to an internal buffer. Retrieve the data with dump(). If target is a binary file, data will be written to the file and flushed when the Writer is destroyed. If target is a callback it will be invoked with generated chunks of bytes. Any exceptions raised in the callback will be propagated up. The callback has the format:

def callback(data):
	return

If pretty is True then whitespace will be added to the output based on use_spaces and the indent_multiple.

dump()

Returns written data as a byte string. Only valid when not serializing with a callback or file.

value(data)

Writes any object, recursively serializing lists and dicts as arrays and objects. Any Typed value is written as a type. Returns self.

object_begin()

Opens an object. Returns self.

object_end()

Ends an open object. Returns self.

array_begin()

Opens an array. Returns self.

array_end()

Ends an open array. Returns self.

key(value)

Writes an object key. Returns self. Only valid in an object.

type(value)

Writes a type. Returns self. Only valid before a primitive, object begin, or array begin.

primitive(value)

Writes a primitive. Returns self.

luxem © Rendaw, Zarbosoft 2017

luxem-python © Rendaw, Zarbosoft 2017