Metadata-Version: 2.4
Name: msgspec-serde
Version: 0.1.1
Requires-Dist: flatbuffers>=24.3.25
Requires-Dist: msgspec>=0.19
Requires-Dist: numpy>=2
License-File: LICENSE
License-File: src/msgspec_serde/_reflection/LICENSE.txt
Summary: Performant serialization helpers for msgspec and flatbuffers
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# msgspec-serde

`msgspec` provides fast `Struct` types and JSON and MessagePack codecs.
FlatBuffers provides compact structured-data representations, lazy access to
serialized data, and schemas for cross-language compatibility.

Each library leaves a gap in Python. The official FlatBuffers Python API
serializes and deserializes very slowly in our benchmarks, and encoding requires
callers to assemble objects through a builder API. `msgspec` needs hooks that
traverse NumPy arrays across the Python/C boundary. `msgspec-serde` combines
`msgspec` models with generated FlatBuffers views and encodes NumPy arrays as
JSON, MessagePack, or FlatBuffers through one API.

## Features

- Generate typed `msgspec.Struct` models and lazy, buffer-backed views from
  FlatBuffers IDL.
  - Use `msgspec_flatc` tool for generating, then subclass the `Struct` classes
    to add standard `msgspec` validation, methods, etc.  ser/de respects subclasses.
  - Tables with `(key)`-annotated fields are converted to dicts (msgspec) / Maps (views).
  - Additional attributes with special handling include `(nested_flatbuffer ...)`,
    `(dynamic_extension)`, `(dynamic_flatbuffer)`, and `(dynamic_allow)`.  See the
    tutorial for more details.
- FAST encoding/decoding of `msgspec.Struct` containing NumPy arrays into
  JSON, MessagePack, and FlatBuffers through dedicated `Encoder` and `Decoder` APIs.
- Dynamic class encoding/decoding using registries is supported using constructed
  hook objects.
- Supports tables, structs, enums, fixed arrays, unions, keyed vectors, schema
  includes, and typed or dynamic nested FlatBuffers.

## Tutorial

See [TUTORIAL.md](TUTORIAL.md) for installation, schema generation, generated
models and views, JSON and MessagePack codecs, unions, nested FlatBuffers, and
dynamic payloads.

## Backward compatibility

Within one major SemVer version, we try to keep Python code generated by an
earlier release working with later `msgspec-serde` runtimes. This project is
young, so backward compatibility is a goal rather than a guarantee.

Forward compatibility is not guaranteed. Code generated by a later release may
not work with an earlier runtime.

Every generated module records the generator version and checks the installed
runtime during import:

- If the major versions differ in either direction, import raises
  `GeneratedCodeVersionError`.
- If the major versions match but the runtime minor version is older, import
  emits `GeneratedCodeVersionWarning` once for that generator/runtime version
  pair.
- Otherwise, import continues without a version warning. Patch-version
  differences do not produce a warning.

To suppress the older-runtime warning, set the process-wide flag before
importing generated modules:

```python
import msgspec_serde

msgspec_serde.warn_on_older_runtime = False
```

The flag does not suppress `GeneratedCodeVersionError` for a major-version
mismatch.

## Benchmarks

- The generated API encodes about 20–22 times faster and materializes models
  about 11–13 times faster than the official Python FlatBuffers API in the
  measured workloads.
- For the recursive numeric workload, MessagePack encodes fastest with
  16-value vectors, while FlatBuffers materializes fastest. With 256-value
  vectors, FlatBuffers is fastest in both directions.

See [benchmarks.md](benchmarks.md) for charts, methodology, environment details,
and reproducible commands.

