DOCSP-46685: BSON

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,128 @@
+.. _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 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+}. 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, perform the following steps:
+
+1. Fetch the documents you want to write to a file.
+#. Open a file stream on the file to write to in write-binary mode.
+#. Write each document to the output file. Ensure that documents are encoded to BSON
+   format by using the ``BSON.encode()`` method.
+
+The following example writes the sample BSON document to ``file.bson``:
+
+.. code-block:: python
+
+   import bson
+
+   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 on the file to read from in
+read-binary mode, then read the documents from the file. Ensure that the documents are
+decoded from BSON format 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()
+             doc = BSON(data).decode()
+             print(doc)
+
+   .. 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 following API documentation:
+
+- `bson <{+api-root+}bson/index.html>`__