# `bson` – BSON (Binary JSON) Encoding and Decoding

BSON (Binary JSON) encoding and decoding.

The mapping from Python types to BSON types is as follows:

Python Type | BSON Type | Supported Direction
--- | --- | ---
None | null | both
bool | boolean | both
int [1] | int32 / int64 | py -> bson
`bson.int64.Int64` | int64 | both
float | number (real) | both
str | string | both
list | array | both
dict | object | both
`SON` | object | both
`Mapping` | object | py -> bson
`RawBSONDocument` | object | both [2]
datetime.datetime [3] [4] | UTC datetime | both
`DatetimeMS` | UTC datetime | both [5]
`Regex` | regex | both
compiled re [7] | regex | py -> bson
`Binary` | binary | both
`uuid.UUID` [6] | binary | both
`ObjectId` | oid | both
`DBRef` | dbref | both
`DBRef` | dbpointer | bson -> py
None | undefined | bson -> py
`Code` | code | both
str | symbol | bson -> py
bytes [8] | binary | both
`Timestamp` | timestamp | both
`Decimal128` | decimal128 | both
`MinKey` | min key | both
`MaxKey` | max key | both

[1]

A Python int will be saved as a BSON int32 or BSON int64 depending on its size. A BSON int32 will always decode to a Python int. A BSON int64 will always decode to a `Int64`.

[2]

Decoding a bson object to `RawBSONDocument` can be optionally configured via `document_class`.

[3]

datetime.datetime instances are encoded with millisecond precision so the microsecond field is truncated.

[4]

all datetime.datetime instances are encoded as UTC. By default, they are decoded as naive but timezone aware datetimes are also supported. See Dates and Times for examples.

[5]

To enable decoding a bson UTC datetime to a `DatetimeMS` instance see handling out of range datetimes.

[6]

For `uuid.UUID` encoding and decoding behavior see https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#universally-unique-ids–uuids-.

[7]

`Regex` instances and regular expression objects from `re.compile()` are both saved as BSON regular expressions. BSON regular expressions are decoded as `Regex` instances.

[8]

The bytes type is encoded as BSON binary with subtype 0. It will be decoded back to bytes.

class bson.BSON

  BSON (Binary JSON) data.

  Warning

  Using this class to encode and decode BSON adds a performance cost. For better performance use the module level functions `encode()` and `decode()` instead.

  decode(codec_options=(<class 'dict'>, False, 0, 'strict', None, TypeRegistry(type_codecs=[], fallback_encoder=None), DatetimeConversion.DATETIME))

    Decode this BSON data.

    By default, returns a BSON document represented as a Python `dict`. To use a different `MutableMapping` class, configure a `CodecOptions`:

        >>> import collections  # From Python standard library.
        >>> import bson
        >>> from bson.codec_options import CodecOptions
        >>> data = bson.BSON.encode({'a': 1})
        >>> decoded_doc = bson.BSON(data).decode()
        <type 'dict'>
        >>> options = CodecOptions(document_class=collections.OrderedDict)
        >>> decoded_doc = bson.BSON(data).decode(codec_options=options)
        >>> type(decoded_doc)
        <class 'collections.OrderedDict'>

    Parameters:

      codec_options (CodecOptions[Any]) – An instance of `CodecOptions`.

    Return type:

      dict[str, Any]

    Changed in version 3.0: Removed compile_re option: PyMongo now always represents BSON regular expressions as `Regex` objects. Use `try_compile()` to attempt to convert from a BSON regular expression to a Python regular expression object.

    Replaced as_class, tz_aware, and uuid_subtype options with codec_options.

  classmethod encode(document, check_keys=False, codec_options=(<class 'dict'>, False, 0, 'strict', None, TypeRegistry(type_codecs=[], fallback_encoder=None), DatetimeConversion.DATETIME))

    Encode a document to a new `BSON` instance.

    A document can be any mapping type (like `dict`).

    Raises `TypeError` if document is not a mapping type, or contains keys that are not instances of `str'. Raises :class:`~bson.errors.InvalidDocument` if document cannot be converted to `BSON`.

    Parameters:

      - document (Mapping[str, Any]) – mapping type representing a document

      - check_keys (bool) – check if keys start with ‘$’ or contain ‘.’, raising `InvalidDocument` in either case

      - codec_options (CodecOptions[Any]) – An instance of `CodecOptions`.

    Return type:

      BSON

    Changed in version 3.0: Replaced uuid_subtype option with codec_options.

bson.decode(data: _ReadableBuffer, codec_options: None = None) → dict[str, Any]
bson.decode(data: _ReadableBuffer, codec_options: CodecOptions[_DocumentType]) → _DocumentType

  Decode BSON to a document.

  By default, returns a BSON document represented as a Python `dict`. To use a different `MutableMapping` class, configure a `CodecOptions`:

      >>> import collections  # From Python standard library.
      >>> import bson
      >>> from bson.codec_options import CodecOptions
      >>> data = bson.encode({'a': 1})
      >>> decoded_doc = bson.decode(data)
      <type 'dict'>
      >>> options = CodecOptions(document_class=collections.OrderedDict)
      >>> decoded_doc = bson.decode(data, codec_options=options)
      >>> type(decoded_doc)
      <class 'collections.OrderedDict'>

  Parameters:

    - data – the BSON to decode. Any bytes-like object that implements the buffer protocol.

    - codec_options – An instance of `CodecOptions`.

  Added in version 3.9.

bson.decode_all(data: _ReadableBuffer, codec_options: None = None) → list[dict[str, Any]]
bson.decode_all(data: _ReadableBuffer, codec_options: CodecOptions[_DocumentType]) → list[_DocumentType]

  Decode BSON data to multiple documents.

  data must be a bytes-like object implementing the buffer protocol that provides concatenated, valid, BSON-encoded documents.

  Parameters:

    - data – BSON data

    - codec_options – An instance of `CodecOptions`.

  Changed in version 3.9: Supports bytes-like objects that implement the buffer protocol.

  Changed in version 3.0: Removed compile_re option: PyMongo now always represents BSON regular expressions as `Regex` objects. Use `try_compile()` to attempt to convert from a BSON regular expression to a Python regular expression object.

  Replaced as_class, tz_aware, and uuid_subtype options with codec_options.

bson.decode_file_iter(file_obj: BinaryIO | IO[bytes], codec_options: None = None) → Iterator[dict[str, Any]]
bson.decode_file_iter(file_obj: BinaryIO | IO[bytes], codec_options: CodecOptions[_DocumentType]) → Iterator[_DocumentType]

  Decode bson data from a file to multiple documents as a generator.

  Works similarly to the decode_all function, but reads from the file object in chunks and parses bson in chunks, yielding one document at a time.

  Parameters:

    - file_obj – A file object containing BSON data.

    - codec_options – An instance of `CodecOptions`.

  Changed in version 3.0: Replaced as_class, tz_aware, and uuid_subtype options with codec_options.

  Added in version 2.8.

bson.decode_iter(data: bytes, codec_options: None = None) → Iterator[dict[str, Any]]
bson.decode_iter(data: bytes, codec_options: CodecOptions[_DocumentType]) → Iterator[_DocumentType]

  Decode BSON data to multiple documents as a generator.

  Works similarly to the decode_all function, but yields one document at a time.

  data must be a string of concatenated, valid, BSON-encoded documents.

  Parameters:

    - data – BSON data

    - codec_options – An instance of `CodecOptions`.

  Changed in version 3.0: Replaced as_class, tz_aware, and uuid_subtype options with codec_options.

  Added in version 2.8.

bson.encode(document, check_keys=False, codec_options=(<class 'dict'>, False, 0, 'strict', None, TypeRegistry(type_codecs=[], fallback_encoder=None), DatetimeConversion.DATETIME))

  Encode a document to BSON.

  A document can be any mapping type (like `dict`).

  Raises `TypeError` if document is not a mapping type, or contains keys that are not instances of `str`. Raises `InvalidDocument` if document cannot be converted to `BSON`.

  Parameters:

    - document (Mapping[str, Any]) – mapping type representing a document

    - check_keys (bool) – check if keys start with ‘$’ or contain ‘.’, raising `InvalidDocument` in either case

    - codec_options (CodecOptions[Any]) – An instance of `CodecOptions`.

  Return type:

    bytes

  Added in version 3.9.

bson.gen_list_name()

  Generate “keys” for encoded lists in the sequence b”0", b”1", b”2", …

  The first 1000 keys are returned from a pre-built cache. All subsequent keys are generated on the fly.

  Return type:

    Generator[bytes, None, None]

bson.has_c()

  Is the C extension installed?

  Return type:

    bool

bson.is_valid(bson)

  Check that the given string represents valid `BSON` data.

  Raises `TypeError` if bson is not an instance of `bytes`. Returns `True` if bson is valid `BSON`, `False` otherwise.

  Parameters:

    bson (bytes) – the data to be validated

  Return type:

    bool

Sub-modules:

- `binary` – Tools for representing binary data to be stored in MongoDB
  - `BINARY_SUBTYPE`
  - `FUNCTION_SUBTYPE`
  - `OLD_BINARY_SUBTYPE`
  - `OLD_UUID_SUBTYPE`
  - `UUID_SUBTYPE`
  - `STANDARD`
  - `PYTHON_LEGACY`
  - `JAVA_LEGACY`
  - `CSHARP_LEGACY`
  - `MD5_SUBTYPE`
  - `COLUMN_SUBTYPE`
  - `SENSITIVE_SUBTYPE`
  - `VECTOR_SUBTYPE`
  - `USER_DEFINED_SUBTYPE`
  - `UuidRepresentation`
  - `BinaryVectorDtype`
  - `BinaryVector`
  - `Binary`
- `code` – Tools for representing JavaScript code
  - `Code`
- `codec_options` – Tools for specifying BSON codec options
  - `CodecOptions`
  - `DatetimeConversion`
  - `TypeCodec`
  - `TypeDecoder`
  - `TypeEncoder`
  - `TypeRegistry`
- `datetime_ms` – Support for BSON UTC Datetime
  - `DatetimeMS`
- `dbref` – Tools for manipulating DBRefs (references to documents stored in MongoDB)
  - `DBRef`
- `decimal128` – Support for BSON Decimal128
  - `Decimal128`
  - `DecimalDecoder`
  - `DecimalEncoder`
  - `create_decimal128_context()`
- `errors` – Exceptions raised by the `bson` package
  - `BSONError`
  - `InvalidBSON`
  - `InvalidDocument`
  - `InvalidId`
  - `InvalidStringData`
- `int64` – Tools for representing BSON int64
  - `Int64`
- `json_util` – Tools for using Python’s `json` module with BSON documents
  - `DatetimeRepresentation`
  - `JSONMode`
  - `JSONOptions`
  - `LEGACY_JSON_OPTIONS`
  - `CANONICAL_JSON_OPTIONS`
  - `RELAXED_JSON_OPTIONS`
  - `DEFAULT_JSON_OPTIONS`
  - `dumps()`
  - `loads()`
  - `object_pairs_hook()`
  - `object_hook()`
  - `default()`
  - `get_size()`
- `max_key` – Representation for the MongoDB internal MaxKey type
  - `MaxKey`
- `min_key` – Representation for the MongoDB internal MinKey type
  - `MinKey`
- `objectid` – Tools for working with MongoDB ObjectIds
  - `ObjectId`
- `raw_bson` – Tools for representing raw BSON documents.
  - Inserting and Retrieving RawBSONDocuments
  - `RawBSONDocument`
- `regex` – Tools for representing MongoDB regular expressions
  - `Regex`
- `son` – Tools for working with SON, an ordered mapping
  - `SON`
- `timestamp` – Tools for representing MongoDB internal Timestamps
  - `Timestamp`
- `tz_util` – Utilities for dealing with timezones in Python
  - `FixedOffset`
  - `utc`