Merge remote-tracking branch 'upstream/master' into docsp-46812-type-hints

Author: mongoKart

config/redirects

@@ -1,6 +1,6 @@
 define: prefix docs/languages/python/pymongo-driver
 define: base https://www.mongodb.com/${prefix}
-define: versions v4.0 v4.1 v4.2 v4.3 v4.4 v4.5 v4.6 v4.7 v4.8 v4.9 4.10 master
+define: versions v4.0 v4.1 v4.2 v4.3 v4.4 v4.5 v4.6 v4.7 v4.8 v4.9 4.10 4.11 master
 
 symlink: current -> master
 

snooty.toml

@@ -31,11 +31,21 @@ mdb-server = "MongoDB Server"
 mongo-community = "MongoDB Community Edition"
 mongo-enterprise = "MongoDB Enterprise Edition"
 docs-branch = "master"                                                       # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
-version-number = "4.10"
-patch-version-number = "{+version-number+}.1"                                # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
+version-number = "4.11"
+patch-version-number = "{+version-number+}"                                # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
 version = "v{+version-number+}"
 stable-api = "Stable API"
 api-root = "https://pymongo.readthedocs.io/en/{+patch-version-number+}/api/"
 string-data-type = "``str``"
 int-data-type = "``int``"
 bool-data-type = "``bool``"
+django-odm = "Django MongoDB Backend"
+django-docs = "https://www.mongodb.com/docs/languages/python/django-mongodb/current"
+
+[[banners]]
+targets = ["index.txt"]
+variant = "tip"
+value = """
+    {+django-odm+} is now in Public Preview! \
+    To discover its features and learn more, see the `{+django-odm+} documentation <{+django-docs+}>`__.
+    """

source/connect.txt

@@ -30,6 +30,7 @@ Connect to MongoDB
    Customize Server Selection </connect/server-selection>
    Stable API </connect/stable-api>
    Limit Server Execution Time </connect/csot>
+   Connection Pools </connect/connection-pools>
 
 Overview
 --------

source/connect/connection-options.txt

@@ -258,8 +258,28 @@ Read and Write Operations
          time plus this value, the server isn't eligible for selection.
        |
        | **Data Type**: `read_preferences <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences>`__
-       | **Default**: ``{+int-data-type+}``
+       | **Default**: {+int-data-type+}
        | **MongoClient Example**: ``localThresholdMS=35``
        | **Connection URI Example**: ``localThresholdMS=35``
 
-For more information about the connection option in this section, see :ref:`pymongo-databases-collections`. 
+   * - **retryReads**
+     - | Specifies whether the client retries supported read operations. For more
+         information, see :manual:`Retryable Reads </core/retryable-reads/>` in the {+mdb-server+}
+         manual.
+       |
+       | **Data Type**: {+bool-data-type+}
+       | **Default**: ``True``
+       | **MongoClient Example**: ``retryReads=False``
+       | **Connection URI Example**: ``retryReads=false``
+
+   * - **retryWrites**
+     - | Specifies whether the client retries supported write operations. For more
+         information, see :manual:`Retryable Writes </core/retryable-writes/>` in the {+mdb-server+}
+         manual.
+       |
+       | **Data Type**: {+bool-data-type+}
+       | **Default**: ``True``
+       | **MongoClient Example**: ``retryWrites=False``
+       | **Connection URI Example**: ``retryWrites=false``
+
+For more information about the connection options in this section, see :ref:`pymongo-databases-collections`. 

source/connect/connection-pools.txt

@@ -0,0 +1,108 @@
+.. _pymongo-connection-pools:
+
+================
+Connection Pools
+================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn about how {+driver-short+} uses connection pools to manage
+connections to a MongoDB deployment and how you can configure connection pool settings
+in your application.
+
+A connection pool is a cache of open database connections maintained by {+driver-short+}.
+When your application requests a connection to MongoDB, {+driver-short+} seamlessly
+gets a connection from the pool, performs operations, and returns the connection
+to the pool for reuse.
+
+Connection pools help reduce application latency and the number of times new connections
+are created by {+driver-short+}.
+
+Configuring Connection Pools
+----------------------------
+
+You can specify the following connection pool settings in your ``MongoClient`` object or in
+your connection URI:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Setting
+     - Description
+
+   * - ``connectTimeoutMS``
+     - | Sets the time that {+driver-short+} waits when connecting a new
+         socket before timing out.
+       | Defaults to ``20000``
+
+   * - ``maxConnecting``
+     - | Sets the maximum number of connections that each pool can establish concurrently.
+         If this limit is reached, further requests wait until a connection is established
+         or another in-use connection is checked back into the pool.
+       | Defaults to ``2``
+
+   * - ``maxIdleTimeMS``
+     - | Sets the maximum time that a connection can remain idle in the pool.
+       | Defaults to ``None`` (no limit)
+
+   * - ``maxPoolSize``
+     - | Sets the maximum number of concurrent connections that the pool maintains.
+         If the maximum pool size is reached, further requests wait until a connection
+         becomes available.
+       | Defaults to ``100``
+
+   * - ``minPoolSize``
+     - | Sets the minimum number of concurrent connections that the pool maintains. If
+         the number of open connections falls below this value due to network errors,
+         {+driver-short+} attempts to create new connections to maintain this minimum.
+       | Defaults to ``0``
+
+   * - ``socketTimeoutMS``
+     - | Sets the length of time that {+driver-short+} waits for a response from the server
+         before timing out.
+       | Defaults to ``None`` (no timeout)
+
+   * - ``waitQueueTimeoutMS``
+     - | Sets how long a thread waits for a connection to become available in the connection pool
+         before timing out.
+       | Defaults to ``None`` (no timeout)
+
+The following code creates a client with a maximum connection pool size of ``50`` by using the
+``maxPoolSize`` parameter:
+
+.. code-block:: python
+
+   client = MongoClient(host, port, maxPoolSize=50)
+
+The following code creates a client with the same configuration as the preceding example,
+but uses a connection URI:
+
+.. code-block:: python
+
+   client = MongoClient("mongodb://<host>:<port>/?maxPoolSize=50")
+
+Additional Information
+----------------------
+
+To learn more about connection pools, see :manual:`Connection Pool Overview </administration/connection-pool-overview/>`
+in the {+mdb-server+} manual.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__ 

source/connect/connection-targets.txt

@@ -9,7 +9,7 @@ Choose a Connection Target
    :values: reference
 
 .. meta::
-   :keywords: connection string, URI, server, settings, client
+   :keywords: connection string, URI, server, settings, client, load balancing
 
 .. contents:: On this page
    :local:
@@ -74,6 +74,15 @@ Replica Sets
 To connect to a replica set, specify the hostnames (or IP addresses) and 
 port numbers of the replica-set members in your connection string.
 
+The following code shows how to use {+driver-short+} to connect to a replica set
+that contains three hosts:
+
+.. code-block:: python
+
+   from pymongo import MongoClient
+   
+   client = MongoClient("mongodb://host1:27017,host2:27017,host3:27017")
+
 If you aren't able to provide a full list of hosts in the replica set, you can 
 specify one or more of the hosts in the replica set and instruct {+driver-short+} to 
 perform automatic discovery to find the others. To instruct the driver to perform
@@ -94,6 +103,11 @@ hosts, including ``host1``:
    uri = "mongodb://host1:27017/?replicaSet=sampleRS"
    client = MongoClient(uri)
 
+{+driver-short+} evenly load balances operations across deployments that are reachable
+within the client's ``localThresholdMS`` value. To learn more about how {+driver-short+} load
+balances operations across multiple MongoDB deployments, see the
+:ref:`pymongo-server-selection` guide.
+
 .. note::
 
    The ``MongoClient`` constructor is *non-blocking*.

source/connect/network-compression.txt

@@ -91,3 +91,10 @@ The following code example specifies the ``zlib`` compression algorithm and a va
                 "compressors=zlib"
                 "zlibCompressionLevel=1")
          client = pymongo.MongoClient(uri)
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
+API documentation.

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.