Skip to main content
The lodum.bson module provides BSON (Binary JSON) serialization and deserialization for lodum-enabled classes with support for streaming.

​
Installation

Requires bson from pymongo. Install with: 
pip install lodum[bson]

​
Functions

​
dump

def dump(
    obj: Any,
    target: Optional[Union[IO[bytes], Path]] = None,
    **kwargs
) -> Optional[bytes]
Encodes a Python object to BSON.
​
obj
Any
required
The object to encode.
​
target
Optional[Union[IO[bytes], Path]]
Optional file-like object or Path to write to.
​
**kwargs
dict
Additional arguments for bson.encode.
Returns: The BSON bytes if target is None, otherwise None. Raises: ImportError if bson (pymongo) is not installed. Note: BSON requires a dictionary at the root. If the object is not a dictionary, it will be wrapped in {"_v": obj}. Example: 
import lodum
from lodum import bson

@lodum
class Person:
    name: str
    age: int

person = Person(name="Alice", age=30)

# Serialize to bytes
bson_bytes = bson.dump(person)

# Serialize to file
bson.dump(person, Path("person.bson"))

​
dumps

def dumps(obj: Any, **kwargs) -> bytes
Legacy alias for dump(obj).
​
obj
Any
required
The object to encode.
​
**kwargs
dict
Additional arguments for bson.encode.
Returns: The BSON bytes.

​
load

def load(
    cls: Type[T],
    source: Union[bytes, IO[bytes], Path],
    max_size: int = DEFAULT_MAX_SIZE
) -> T
Decodes BSON from bytes, stream, or file into a Python object.
​
cls
Type[T]
required
The class to instantiate.
​
source
Union[bytes, IO[bytes], Path]
required
BSON bytes, file-like object, or Path.
​
max_size
int
default:"DEFAULT_MAX_SIZE"
Maximum allowed size for bytes input.
Returns: An instance of cls. Raises:
  • ImportError if bson (pymongo) is not installed.
  • DeserializationError if the input is invalid or exceeds max_size.
Note: If the BSON document contains only a _v key (from wrapping), it will be automatically unwrapped. Example: 
import lodum
from lodum import bson

@lodum
class Person:
    name: str
    age: int

# Load from bytes
bson_bytes = b'\x1a\x00\x00\x00...'
person = bson.load(Person, bson_bytes)

# Load from file
person = bson.load(Person, Path("person.bson"))

​
loads

def loads(cls: Type[T], bson_bytes: bytes, **kwargs) -> T
Legacy alias for load(cls, source).
​
cls
Type[T]
required
The class to instantiate.
​
bson_bytes
bytes
required
BSON bytes to parse.
​
**kwargs
dict
Additional arguments (e.g., max_size).
Returns: An instance of cls.

​
stream

def stream(cls: Type[T], source: Union[IO[bytes], Path]) -> Iterator[T]
Lazily decodes a stream of BSON objects. Supports concatenated BSON objects.
​
cls
Type[T]
required
The class to instantiate for each item.
​
source
Union[IO[bytes], Path]
required
A binary stream, file-like object, or Path.
Returns: An iterator yielding instances of cls. Raises:
  • ImportError if bson (pymongo) is not installed.
  • DeserializationError if the source type is unsupported for streaming.
Example: 
import lodum
from lodum import bson

@lodum
class Person:
    name: str
    age: int

# Stream from file containing concatenated BSON objects
for person in bson.stream(Person, Path("people.bson")):
    print(person.name, person.age)

​
Notes

  • BSON is the binary format used by MongoDB
  • BSON requires a dictionary at the root level, so non-dict objects are wrapped
  • The decode_file_iter function handles concatenated BSON documents efficiently
  • Native bytes support without base64 encoding

Build docs developers (and LLMs) love

Get started for freeTalk to us