Metadata-Version: 2.4
Name: msgspec-serde
Version: 0.1.0
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: Generate lazy FlatBuffers views and msgspec models from FlatBuffers schemas
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# msgspec-serde

On the one hand:

- `msgspec.Struct` objects are extremely efficient and convenient replacements
   for `dataclass`; and `msgspec` JSON encoders and decoders are extremely efficient.
- FlatBuffers offer both extremely efficient representations of structured data,
  and a declaration format that allows cross-language compatibility.

On the other hand:
* FlatBuffers' Python API has extremely inefficient ser/de and an inconvenient
  builder pattern.
* `msgspec` ser/de of np.arrays isn't very efficient and requires encoder/decoder
  hooks that traverse the python/C boundary.

`msgspec-serde` solves these two issues.  It merges the features of FlatBuffers with `msgspec`
and enables efficient encoding/decoding of NumPy arrays across JSON, MessagePack, and FlatBuffers
in one convenient package!

## 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.

