From 8b957552fe4c2c46673574d8b552c5506d3173bc Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 18 Feb 2025 11:25:31 -0500 Subject: [PATCH 1/6] DOCSP-47282: RawBSONDocument information --- source/data-formats/bson.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index d0a36209..0edd51c8 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -117,6 +117,32 @@ The following example reads the sample BSON document from ``file.bson``: {"address": {"street": "Pizza St", "zipcode": "10003"}, "coord": [-73.982419, 41.579505], "cuisine": "Pizza", "name": "Mongo's Pizza"} +RawBSONDocument +--------------- + +You might prefer to use raw BSON documents in certain cases, such as when you move a +document between databases or collections, when you must write binary blobs to a +disk, or when you want to bypass the performance overhead of converting to and from +{+language+} dictionaries. You can use the ``RawBSONDocument`` class to represent raw BSON +documents. To use ``RawBSONDocument`` objects with your collection, set the +``document_class`` parameter of the ``MongoClient`` constructor to ``RawBSONDocument``. + +The following example fetches the sample BSON document from a collection and converts it +to a ``RawBSONDocument``: + +.. code-block:: python + + from bson.raw_bson import RawBSONDocument + + client = pymongo.MongoClient("", document_class=RawBSONDocument) + collection = client[""][""] + raw_doc = collection.find_one({"name": "Mongo's Pizza"}) + +.. note:: + + ``RawBSONDocument`` objects are read-only. To modify a ``RawBSONDocument``, you must + first convert it to a {+language+} dictionary. + API Documentation ----------------- From 21d6199269ceeb3cf4042bad4be9fb53266487d3 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 18 Feb 2025 11:46:43 -0500 Subject: [PATCH 2/6] Fix --- source/data-formats/bson.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 0edd51c8..57962686 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -117,8 +117,8 @@ The following example reads the sample BSON document from ``file.bson``: {"address": {"street": "Pizza St", "zipcode": "10003"}, "coord": [-73.982419, 41.579505], "cuisine": "Pizza", "name": "Mongo's Pizza"} -RawBSONDocument ---------------- +Work with Raw BSON Data +----------------------- You might prefer to use raw BSON documents in certain cases, such as when you move a document between databases or collections, when you must write binary blobs to a From 096dc26f90713148358119ce30210eee739567aa Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 18 Feb 2025 12:36:30 -0500 Subject: [PATCH 3/6] RR feedback --- source/data-formats/bson.txt | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 57962686..99b52a85 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -120,15 +120,19 @@ The following example reads the sample BSON document from ``file.bson``: Work with Raw BSON Data ----------------------- -You might prefer to use raw BSON documents in certain cases, such as when you move a -document between databases or collections, when you must write binary blobs to a -disk, or when you want to bypass the performance overhead of converting to and from -{+language+} dictionaries. You can use the ``RawBSONDocument`` class to represent raw BSON -documents. To use ``RawBSONDocument`` objects with your collection, set the +{+driver-short+} supports the usage of raw BSON documents. The following list contains +some situations that might require using raw BSON documents: + +- Moving a document between databases or collections +- Writing binary blobs to a disk +- Bypassing the performance overhead of converting to and from {+language+} dictionaries. + +You can use the ``RawBSONDocument`` class to represent raw BSON documents. To use +``RawBSONDocument`` objects to represent documents in your collection, set the ``document_class`` parameter of the ``MongoClient`` constructor to ``RawBSONDocument``. -The following example fetches the sample BSON document from a collection and converts it -to a ``RawBSONDocument``: +The following example configures a ``MongoClient`` object to use ``RawBSONDocument``, +then retrieves the sample document: .. code-block:: python From 4131fe38319236582f2f2a2f756eab36183e74c3 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 18 Feb 2025 12:51:29 -0500 Subject: [PATCH 4/6] Fix --- source/data-formats/bson.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 99b52a85..0c7e6d2f 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -125,7 +125,7 @@ some situations that might require using raw BSON documents: - Moving a document between databases or collections - Writing binary blobs to a disk -- Bypassing the performance overhead of converting to and from {+language+} dictionaries. +- Bypassing the performance overhead of converting to and from {+language+} dictionaries You can use the ``RawBSONDocument`` class to represent raw BSON documents. To use ``RawBSONDocument`` objects to represent documents in your collection, set the From 906a7709b9b69bbec80c64b9291406616f0d76ea Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 18 Feb 2025 14:47:26 -0500 Subject: [PATCH 5/6] RR feedback --- source/data-formats/bson.txt | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 0c7e6d2f..92b4e31e 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -124,23 +124,34 @@ Work with Raw BSON Data some situations that might require using raw BSON documents: - Moving a document between databases or collections -- Writing binary blobs to a disk +- Writing binary data to a disk - Bypassing the performance overhead of converting to and from {+language+} dictionaries -You can use the ``RawBSONDocument`` class to represent raw BSON documents. To use -``RawBSONDocument`` objects to represent documents in your collection, set the -``document_class`` parameter of the ``MongoClient`` constructor to ``RawBSONDocument``. +The ``RawBSONDocument`` class is a representation of a BSON document that provides +access to the underlying raw BSON bytes. To use ``RawBSONDocument`` objects to represent +documents in your collection, set the ``document_class`` parameter of the ``MongoClient`` +constructor to ``RawBSONDocument``. -The following example configures a ``MongoClient`` object to use ``RawBSONDocument``, -then retrieves the sample document: +The following example configures a ``MongoClient`` object to use ``RawBSONDocument`` objects +to model the collection, then retrieves the sample document from the preceding examples: -.. code-block:: python +.. io-code-block:: + :copyable: true + + .. input:: + :language: python from bson.raw_bson import RawBSONDocument client = pymongo.MongoClient("", document_class=RawBSONDocument) - collection = client[""][""] + collection = client.sample_restaurants.restaurants raw_doc = collection.find_one({"name": "Mongo's Pizza"}) + print(type(raw_doc)) + + .. output:: + :visible: false + + .. note:: From 32dbd31ad63cf534bda637d2ebf2dcc91a8aa25c Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 19 Feb 2025 15:10:42 -0500 Subject: [PATCH 6/6] NS feedback --- source/data-formats/bson.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 92b4e31e..3a91f882 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -132,6 +132,11 @@ access to the underlying raw BSON bytes. To use ``RawBSONDocument`` objects to r documents in your collection, set the ``document_class`` parameter of the ``MongoClient`` constructor to ``RawBSONDocument``. +.. note:: + + ``RawBSONDocument`` objects are read-only. To modify a ``RawBSONDocument``, you must + first convert it to a {+language+} dictionary. + The following example configures a ``MongoClient`` object to use ``RawBSONDocument`` objects to model the collection, then retrieves the sample document from the preceding examples: @@ -153,11 +158,6 @@ to model the collection, then retrieves the sample document from the preceding e -.. note:: - - ``RawBSONDocument`` objects are read-only. To modify a ``RawBSONDocument``, you must - first convert it to a {+language+} dictionary. - API Documentation -----------------