DOCSP-46685: BSON (#159)

(cherry picked from commit 11167f1)

Author: mcmorisi

source/data-formats.txt

@@ -21,6 +21,7 @@ Specialized Data Formats
    :titlesonly:
    :maxdepth: 1
 
+   BSON </data-formats/bson>
    Custom Types </data-formats/custom-types>
    Dates & Times </data-formats/dates-and-times>
    UUIDs </data-formats/uuid>
@@ -33,6 +34,7 @@ You can use several types of specialized data formats in your {+driver-short+}
 application. To learn how to work with these data formats, see the following
 sections:
 
+- Learn how to work with BSON documents in the :ref:`pymongo-bson` guide.
 - Learn how to encode and decode custom types in the :ref:`pymongo-custom-types` guide.
 - Learn how to work with Python ``datetime`` objects in {+driver-short+} in the
   :ref:`pymongo-dates-times` guide.

source/data-formats/bson.txt

@@ -0,0 +1,124 @@
+.. _pymongo-bson:
+
+====
+BSON
+====
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to create BSON documents, read BSON from a file, 
+and write BSON to a file by using {+driver-short+}.
+
+**BSON**, or Binary JSON, is the data format that MongoDB uses to organize
+and store data. This data format includes all JSON data structure types and
+adds support for types including dates, different size integers, ObjectIds, and
+binary data. You can use BSON documents in your {+language+} application by including the
+`bson <{+api-root+}bson/index.html>`__ package. For a complete list of supported types, see the
+:manual:`BSON Types </reference/bson-types>` server manual page.
+
+The code samples in this guide use the following BSON document as an example:
+
+.. code-block:: none
+
+   {
+       "address" : {
+           "street" : "Pizza St", 
+           "zipcode" : "10003" 
+       },
+       "coord" : [-73.982419, 41.579505]
+       "cuisine" : "Pizza",
+       "name" : "Mongo's Pizza"
+   }
+
+Create a BSON Document
+----------------------
+
+You can create a BSON document by using the same notation you use to create a
+dictionary in {+language+}. {+driver-short+} automatically converts {+language+} dictionaries
+into BSON documents when inserting them into a collection.
+
+The following example creates a BSON document that
+represents the preceding sample BSON document:
+
+.. code-block:: python
+
+   document = {
+       "address": {
+           "street": "Pizza St",
+           "zipcode": "10003"
+       },
+       "coord": [-73.982419, 41.579505],
+       "cuisine": "Pizza",
+       "name": "Mongo's Pizza"
+   }
+
+Change a BSON Document
+----------------------
+
+You can modify the contents of a BSON document by using the same notation you use to modify
+a dictionary in {+language+}. The following example makes three changes to the previous
+BSON document:
+
+1. Adds a new field, ``restaurant_id``, with the value ``12345``
+#. Removes the ``cuisine`` field
+#. Sets the value of the ``name`` field to ``"Mongo's Pizza Place"``
+
+.. code-block:: python
+
+   document["restaurant_id"] = 12345
+   del document["cuisine"]
+   document["name"] = "Mongo's Pizza Place"   
+
+Write BSON to a File
+--------------------
+
+To write BSON data to a file, open a file stream in write-binary mode on the output file.
+Then, write each document to the output file. Ensure that documents are encoded in BSON
+format by using the ``bson.encode()`` method.
+
+The following example writes the sample BSON document to ``file.bson``:
+
+.. code-block:: python
+
+   with open("file.bson", "w") as file:
+       file.write(bson.encode(document))
+
+Read BSON from a File
+---------------------
+
+To read BSON documents from a file, open a file stream in read-binary mode on the input
+file. Then, decode the documents from BSON format as you read them by using the ``bson.decode()``
+method.
+
+The following example reads the sample BSON document from ``file.bson``:
+
+.. io-code-block::
+   :copyable: true
+     
+   .. input::
+      :language: python
+
+         with open("file.bson", "rb") as file:
+             data = file.read()
+             document = bson.decode(data)
+             print(document)
+
+   .. output::
+      :visible: false
+      
+      {"address": {"street": "Pizza St", "zipcode": "10003"}, "coord": [-73.982419, 41.579505], "cuisine": "Pizza", "name": "Mongo's Pizza"}
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the `bson <{+api-root+}bson/index.html>`__ API documentation.