obj2bin 0.0.3

A simple object serialization library

obj2bin

A simple object serialization library. Define the data structure with classes and let obj2bin deal with the serialization.

import binascii

from obj2bin import Const, Field, pack, encode, decode, utf8tobytes, utf8frombytes, utf8size

@pack(
  packet_id=Const(1, "B"),
  user_id=Field(">H"),
  name_size=Field("B", meta=True),
  name=Field("<{name_size}s", enc=utf8tobytes, dec=utf8frombytes)
)
class User:
  user_id: int
  name: str
  @property
  def name_size(self) -> int: return utf8size(self.name)

user = User(13, "John")
print(user)
buff, size = encode(user)
print(binascii.hexlify(buff).decode("utf-8"), size)
print(*decode(User, buff))

# output:
#   User(user_id=13, name='John')
#   01000d044a6f686e 8
#   User(user_id=13, name='John') 8

Note: Refer to example.py for a more complete demonstration.

Python's struct module is used to serialize data to bytes. How each object attribute is serialized is determined by the fmt parameter which expects a struct format string.

The order the fields will be encoded is determined by the order of the keyword arguments passed to the @pack() decorator. Because of this, dictionary insertion order must be maintained and, therefore, obj2bin requires Python >= 3.7. This requirement is planned to be removed in the future.

Field types

Field

A field with a dynamic value. The value to be serialized is taken from the object's attribute whose name matches the keyword entry name.

Const

A field with a constant value. If, when being decoded, the value does not match the one specified in Const an exception will be raised. Useful for defining attributes which identify a packet (e.g. packet type identifier or version).

Child

A field which serializes another object. Multiple objects can be specified for the same field.