BSON Codec for Python

Warnings

• breaking Installing 'bson' from PyPI can cause conflicts and `ImportError` when PyMongo is also installed. PyMongo ships with its own `bson` package, and the independent 'bson' package from PyPI is incompatible.
  Fix: If using PyMongo, rely on its internal `bson` module (`from bson import ObjectId` will import PyMongo's version). If you need the independent 'bson' library, ensure it's installed in an isolated environment or consider using `pip install py-bson` if a renamed package becomes available to avoid the name clash. If you encounter issues, `pip uninstall bson pymongo` then `pip install pymongo` (or `pip install bson` if you *only* need the independent bson) is often required.
• gotcha `bson.dumps()` only supports BSON-defined data types. Attempting to encode custom Python objects (e.g., instances of custom classes) directly will raise a `TypeError`.
  Fix: For complex or custom Python objects, convert them into BSON-compatible Python types (like dictionaries, lists, basic types) before passing them to `bson.dumps()`.
• gotcha Decoding invalid, corrupted, or truncated BSON data will raise `bson.errors.InvalidBSON`.
  Fix: Always wrap `bson.loads()` calls in a `try...except bson.errors.InvalidBSON` block to gracefully handle malformed input. Ensure BSON data is complete and correctly formatted before decoding.
• gotcha When encoding `datetime` objects, using `datetime.now()` without specifying a timezone can lead to ambiguity. It's best practice to use `datetime.utcnow()` for naive UTC timestamps or timezone-aware `datetime` objects.
  Fix: Prefer `datetime.now(timezone.utc)` or `datetime.utcnow()` when creating `datetime` objects to be encoded into BSON to avoid timezone-related issues during serialization and deserialization.
• gotcha Release 0.4.5 was skipped due to a 'version issue with pypi'. While not directly impacting users, it indicates potential historical inconsistencies in the release process.
  Fix: No direct fix needed, but be aware of minor version gaps in the historical release sequence.

Install

• pip install bson Install BSON library

Imports

• dumps

  import bson; bson.dumps(...)

• loads

  import bson; bson.loads(...)

• ObjectId

  from bson.objectid import ObjectId

• InvalidBSON

  from bson.errors import InvalidBSON

  Exceptions like InvalidBSON are in the bson.errors submodule, not directly under bson.
• BSON

  import bson; bson.BSON(...)

  While 'BSON' is a class, module-level functions like dumps/loads are generally preferred for performance and simplicity. Direct import of the class is less common.
• json_util

  from bson import json_util

  While PyMongo also has a json_util, this 'bson' library provides its own, though it's less commonly used than dumps/loads for raw BSON.

Quickstart

This example demonstrates how to encode a Python dictionary containing common BSON types (string, datetime, ObjectId, float, list) into BSON bytes using `bson.dumps()`, and then decode it back into a Python dictionary using `bson.loads()`. It also shows how to catch `bson.errors.InvalidBSON` for corrupted or invalid BSON data.

import bson
from bson.objectid import ObjectId
from datetime import datetime, timezone

# Create a Python dictionary with BSON-compatible types
data = {
    "message": "Hello BSON!",
    "timestamp": datetime.now(timezone.utc), # Use timezone-aware datetime for best practice
    "_id": ObjectId(),
    "value": 123.45,
    "tags": ["python", "bson", "example"]
}

# Encode the dictionary to BSON bytes
bson_data = bson.dumps(data)
print(f"Encoded BSON (bytes): {bson_data}")

# Decode the BSON bytes back to a Python dictionary
decoded_data = bson.loads(bson_data)
print(f"Decoded data: {decoded_data}")
print(f"Type of decoded_data: {type(decoded_data)}")
print(f"Type of _id in decoded_data: {type(decoded_data['_id'])}")

# Demonstrate handling InvalidBSON
try:
    bson.loads(b"invalid_bson_data")
except bson.errors.InvalidBSON as e:
    print(f"Caught expected error: {e}")