Metadata-Version: 2.1
Name: miniserial
Version: 0.2.3
Summary: Simple, fast, and space-efficient (de)serialization for simple Python classes
Project-URL: Homepage, https://github.com/SinclaM/miniserial
Author-email: Matthew Sinclair <sinclam.dev@gmail.com>
License: MIT License
        
        Copyright (c) 2023 Matthew Sinclair
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: serialization,serialize
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Requires-Dist: typing-inspect==0.8.0
Description-Content-Type: text/markdown

# Miniserial

Miniserial is a Python package for dead-simple, space-efficient serialization
and deserialization of simple dataclasses. There are many great packages for
general purpose serialization in the standard library and on PyPI (e.g. `json`,
`marshal`, `pickle`, `ujson`, `bson`, etc.), but most use serialization
formats that can come with significant byte overhead. Sometimes, project
constraints—like the 256-byte-max-packet radio devices that inspired this
package—encourage the use of a much more compact format, something akin to
protobuf or the layout of C structs. But libraries in this space typically come
with the overhead of implementing manual serializers, modifying class fields
with various wrappers, or using non python data specifications (e.g. `.proto`
files). `msgpack` comes close, but does not work out of the box with classes.
Miniserial makes compact serialization easy. Simply have your
dataclass inherit from the `Serialization` mixin, and `serialize` and
`deserialize` methods will be automatically generated for the class.
For example:

```python3
from dataclasses import dataclass
from miniserial import Serializable

@dataclass
class Person(Serializable):
    name   : str
    age    : int
    titles : list[str]
    balance: float
    
p = Person("Bob", 34, ["Mr.", "Dr.", "Professor"], 239847.25)
assert Person.deserialize(p.serialize()) == p
```

Classes that inherit the `Serializable` mixin must be dataclasses composed of
fields annotated with supported types, which include any other class which
inherits `Serializable`. This means that even recursive structures,
like trees, can be serialized and deserialized.

```python3
from __future__ import annotations
from dataclasses import dataclass
from miniserial import Serializable

@dataclass
class Node(Serializable):
    value   : int
    children: list[Node]

#                 1
#               /   \ 
#              2     3 
#             / \
#            4   5
tree = Node(1, [Node(2, [Node(4, []), Node(5, [])]), Node(3, [])])
assert Node.deserialize(tree.serialize()) == tree
```

Documentation of supported types and the serialization format is on the way. For
now, `bool`, `int`, `float`, `str`, and subclasses of `collections.abc.Collection`
(e.g. `list`, `set`, `tuple`) are supported, along with any other user-defined
class that inherits `Serializable`. `int` and `float` are taken to be 32 bit
values. Support for more types, including `int64`, `float64`, etc. from `numpy`
are on the horizon.
