tessl/pypi-bson

Independent BSON codec for Python that doesn't depend on MongoDB

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Core Serialization

Name: tessl/pypi-bson
Author: tessl

Primary BSON encoding and decoding functionality that forms the foundation of the bson package. These functions provide complete serialization capabilities for converting between Python objects and BSON binary format.

Capabilities

BSON Serialization

Converts Python dictionaries and BSONCoding objects to BSON binary format with optional custom encoding order generation and unknown type handling.

def dumps(obj, generator=None, on_unknown=None):
    """
    Convert a Python object to BSON bytes.

    Parameters:
    - obj: dict or BSONCoding object to serialize
    - generator: Optional function that accepts (dict/array, traversal_stack) 
                and returns iterator for encoding order of keys
    - on_unknown: Optional function to handle unknown types during encoding

    Returns:
    bytes: BSON-encoded data

    Raises:
    UnknownSerializerError: If unknown type encountered and no on_unknown handler
    """

Usage example:

import bson

# Basic serialization
data = {"name": "Alice", "age": 30, "items": ["book", "pen"]}
bson_data = bson.dumps(data)

# With custom key ordering
def custom_order(obj, stack):
    if isinstance(obj, dict):
        # Sort keys alphabetically
        return sorted(obj.keys())
    return obj.keys()

ordered_bson = bson.dumps(data, generator=custom_order)

# With unknown type handler
def handle_unknown(value):
    if hasattr(value, '__dict__'):
        return value.__dict__
    return str(value)

complex_data = {"obj": SomeCustomObject(), "value": 42}
bson_data = bson.dumps(complex_data, on_unknown=handle_unknown)

BSON Deserialization

Converts BSON binary data back to Python dictionaries, automatically handling all supported BSON types and custom BSONCoding objects.

def loads(data):
    """
    Convert BSON bytes to a Python object.

    Parameters:
    - data: bytes, BSON-encoded data to deserialize

    Returns:
    dict: Deserialized Python object (usually dict)

    Raises:
    ValueError: If BSON data is malformed or invalid
    MissingClassDefinition: If custom object class not registered
    """

Usage example:

import bson

# Basic deserialization
bson_data = b'\x1a\x00\x00\x00\x02name\x00\x06\x00\x00\x00Alice\x00\x10age\x00\x1e\x00\x00\x00\x00'
obj = bson.loads(bson_data)
print(obj)  # {'name': 'Alice', 'age': 30}

# Handles all BSON types automatically
complex_bson = bson.dumps({
    "string": "hello",
    "number": 42,
    "float": 3.14,
    "bool": True,
    "null": None,
    "array": [1, 2, 3],
    "nested": {"key": "value"}
})
restored = bson.loads(complex_bson)

Error Handling

Serialization Errors

class UnknownSerializerError(ValueError):
    """Raised when unable to serialize unknown type"""
    def __init__(self, key, value): ...

Occurs when dumps() encounters a type it cannot serialize and no on_unknown handler is provided.

Deserialization Errors

Common errors during deserialization:

ValueError: Malformed BSON data, missing null terminators, invalid structure
MissingClassDefinition: Custom BSONCoding class not registered with import_class()
UnicodeDecodeError: Invalid UTF-8 strings in BSON data

Type Conversion Details

Automatic Type Handling

The serialization functions automatically handle type conversion between Python and BSON:

Python Type	BSON Type	Notes
`bool`	Boolean	Must be checked before `int`
`int`	Int32/Int64/UInt64	Based on value range
`float`	Double	IEEE 754 double precision
`str`/`unicode`	String	UTF-8 encoded
`bytes`	Binary	Binary subtype 0
`dict`	Document	Recursive encoding
`list`/`tuple`	Array	Indexed as string keys
`datetime`	UTCDateTime	Milliseconds since epoch
`None`	Null	BSON null type
`UUID`	Binary	Binary subtype 4
`Decimal`	Double	Converted to float

Custom Type Integration

For explicit type control, use the type wrapper classes:

from bson.types import Int32, Int64, UInt64

data = {
    "small_int": Int32(100),
    "big_int": Int64(9223372036854775807),
    "unsigned": UInt64(18446744073709551615)
}
bson_data = bson.dumps(data)

Install with Tessl CLI