compaqt 1.0.0

A compact serializer aiming for flexibility and performance

Compaqt

A compact serializer aiming for flexibility and performance.

What is this?

Compaqt is an efficient serializer that aims for speed and compactness. Its purpose is similar to other libraries like JSON, except Compaqt uses a binary format to keep the data sizes low and the performance high.

This library also aims to be flexible and has an easy-to-use API, providing methods for directly using files, chunk processing, and data validation.

Besides the 'standard' types, this serializer supports custom types and lets you assign your own functions to serialize and de-serialize custom types.

How do I use it?

For 'simple' serialization, this library provides the encode and decode methods. These methods directly return the encoded data as bytes or the value decoded from encoded data, respectively. Here's a simple example on how this works:

import compaqt

# The value we want to serialize, can be anything
value = ...

# We can just use the `encode` method to serialize it, that's all we have to do!
encoded = compaqt.encode(value)

# Do stuff
...

# Now, we want to retrieve the value we originally had, which we currently hold in the `encoded` variable
# For this, all we have to do is use the `decode` method:
value = compaqt.decode(encoded)

# Now, `value` holds the original value, exactly as it was when we encoded it earlier

If we want to write the result to a file, and later read it from the file, we can use the optional file_name argument:

# The file we want to write data to
file_name = 'dir/file.bin'

# Pass the filename to the function to write it to said file, instead of having the function return the bytes back directly
compaqt.encode(value, file_name=file_name)

# Do stuff
...

# Now, we want to read the value back from the file.
# We only have to give `decode` the `file_name` argument this time, no need to pass anything else!
value = compaqt.decode(file_name=file_name)

For more advanced streaming functionality, we can use the StreamEncoder and StreamDecoder classes. These support incremental reading and writing, and internally use chunk processing to optimize memory usage.

Apart from serialization, if we need to be sure that some bytes are valid, we can verify the validity of them using the validate method. This supports both direct verification and through streaming, and for streaming also supports all advanced file management features from the StreamEncoder and StreamDecoder objects. This method also has optional chunk processing when streaming.

For further details on how to use this library, please consult the USAGE.

Installation

To install this module for Python, simply run this: pip install compaqt

The library automatically accounts for system endianness and will always convert numbers on big-endian systems to little-endian format. This uses intrinsics with the GCC, Clang, and MSVC compilers, making this endianness conversion neglectible in performance. For the low-level enthusiast: these intrinsics typically translate to a single BSWAP instruction, which executes in just 1-3 CPU cycles.

License

This project is licensed under the BSD-3-Clause License. See the LICENSE file for details.

Contact

Feel free to reach out via the GitHub repo of this module or reach out by mail.