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 / SON |
object |
both |
date |
both |
|
bson.regex.Regex |
regex |
both |
compiled re [4] |
regex |
py -> bson |
bson.binary.Binary |
binary |
both |
bson.objectid.ObjectId |
oid |
both |
bson.dbref.DBRef |
dbref |
both |
None |
undefined |
bson -> py |
bson.code.Code |
code |
both |
str |
symbol |
bson -> py |
bytes [5] |
binary |
both |
- class bson.BSON#
BSON (Binary JSON) data.
警告
Using this class to encode and decode BSON adds a performance cost. For better performance use the module level functions
encode()
anddecode()
instead.- decode(codec_options: CodecOptions[_DocumentType] = CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.UNSPECIFIED, unicode_decode_error_handler='strict', tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None), datetime_conversion=DatetimeConversion.DATETIME)) _DocumentType #
Decode this BSON data.
By default, returns a BSON document represented as a Python
dict
. To use a differentMutableMapping
class, configure aCodecOptions
:>>> 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 (optional): An instance of
CodecOptions
.
在 3.0 版本发生变更: Removed compile_re option: PyMongo now always represents BSON regular expressions as
Regex
objects. Usetry_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: Mapping[str, Any], check_keys: bool = False, codec_options: CodecOptions = CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.UNSPECIFIED, unicode_decode_error_handler='strict', tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None), datetime_conversion=DatetimeConversion.DATETIME)) BSON #
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 ofstr'. Raises :class:`~bson.errors.InvalidDocument
if document cannot be converted toBSON
.- Parameters:
document: mapping type representing a document
check_keys (optional): check if keys start with '$' or contain '.', raising
InvalidDocument
in either casecodec_options (optional): An instance of
CodecOptions
.
在 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 differentMutableMapping
class, configure aCodecOptions
:>>> 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 (optional): An instance of
CodecOptions
.
在 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 (optional): An instance of
CodecOptions
.
在 3.9 版本发生变更: Supports bytes-like objects that implement the buffer protocol.
在 3.0 版本发生变更: Removed compile_re option: PyMongo now always represents BSON regular expressions as
Regex
objects. Usetry_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, codec_options: None = None) Iterator[Dict[str, Any]] #
- bson.decode_file_iter(file_obj: BinaryIO | IO, 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 (optional): An instance of
CodecOptions
.
在 3.0 版本发生变更: Replaced as_class, tz_aware, and uuid_subtype options with codec_options.
在 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 (optional): An instance of
CodecOptions
.
在 3.0 版本发生变更: Replaced as_class, tz_aware, and uuid_subtype options with codec_options.
在 2.8 版本加入.
- bson.encode(document: Mapping[str, Any], check_keys: bool = False, codec_options: CodecOptions = CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.UNSPECIFIED, unicode_decode_error_handler='strict', tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None), datetime_conversion=DatetimeConversion.DATETIME)) bytes #
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 ofstr
. RaisesInvalidDocument
if document cannot be converted toBSON
.- Parameters:
document: mapping type representing a document
check_keys (optional): check if keys start with '$' or contain '.', raising
InvalidDocument
in either casecodec_options (optional): An instance of
CodecOptions
.
在 3.9 版本加入.
- bson.gen_list_name() Generator[bytes, None, None] #
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.
- bson.is_valid(bson: bytes) bool #
Check that the given string represents valid
BSON
data.Raises
TypeError
if bson is not an instance ofbytes
. ReturnsTrue
if bson is validBSON
,False
otherwise.- Parameters:
bson: the data to be validated
Sub-modules:
binary
-- Tools for representing binary data to be stored in MongoDBcode
-- Tools for representing JavaScript codecodec_options
-- Tools for specifying BSON codec optionsdatetime_ms
-- Support for BSON UTC Datetimedbref
-- Tools for manipulating DBRefs (references to documents stored in MongoDB)decimal128
-- Support for BSON Decimal128errors
-- Exceptions raised by thebson
packageint64
-- Tools for representing BSON int64json_util
-- Tools for using Python'sjson
module with BSON documentsmax_key
-- Representation for the MongoDB internal MaxKey typemin_key
-- Representation for the MongoDB internal MinKey typeobjectid
-- Tools for working with MongoDB ObjectIdsraw_bson
-- Tools for representing raw BSON documents.regex
-- Tools for representing MongoDB regular expressionsson
-- Tools for working with SON, an ordered mappingtimestamp
-- Tools for representing MongoDB internal Timestampstz_util
-- Utilities for dealing with timezones in Python