Merge branch 'master' into docsp-46687-collations

Author: mongoKart

.github/pull_request_template.md

@@ -3,7 +3,9 @@
 [PR Reviewing Guidelines](https://github.com/mongodb/docs-node/blob/master/REVIEWING.md)
 
 JIRA - <https://jira.mongodb.org/browse/DOCSP-NNNNN>
-Staging - <https://docs-mongodbcom-staging.corp.mongodb.com/drivers/docsworker-xlarge/NNNNN/>
+
+### Staging Links
+<!-- start insert-links --><!-- end insert-links -->
 
 ## Self-Review Checklist
 

.github/workflows/add-netlify-links.yml

@@ -0,0 +1,58 @@
+name: Add Netlify Links To Changed Pages
+on:
+  workflow_call:
+  pull_request_target:
+jobs:
+  get-pr-changes:
+    name: Get Changed Files & Update PR Description
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      contents: write
+      pull-requests: write
+      repository-projects: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Get Changed Files
+        id: changed-files
+        # pin to a specific commit to ensure stability
+        uses: tj-actions/changed-files@c65cd883420fd2eb864698a825fc4162dd94482c
+        with:
+          separator: ","
+          files: source/**
+      - name: Build Netlify Links for Changed Pages
+        id: build_page_links
+        env:
+          CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
+        run: |
+          new_links=""
+          base_link='https://deploy-preview-${{ github.event.number }}--docs-pymongo.netlify.app'
+          files=$(echo "$CHANGED_FILES" | tr "," "\n")
+          for file in $files; do
+            echo "processing ${file}"
+            if (! grep -s "includes/"  <<< "$file") && 
+                (! grep -s "images/"  <<< "$file") && 
+                (! grep -s "examples/"  <<< "$file"); then
+              file="${file#source}"
+              file="${file%.txt}"
+              filenoslash="${file:1}"
+              echo "${base_link}${file}"
+              new_links+="<li><a href=${base_link}${file}>${filenoslash}</a></li>"
+            else
+              echo "(file skipped)"
+            fi
+          done
+          if [ "$new_links" == "" ]; then
+            new_links="No pages to preview"
+          fi
+          echo "Final new_links string: "
+          echo "${new_links}"
+          echo "staging_links=${new_links}" >> "$GITHUB_OUTPUT"
+      - name: Update the PR Description
+        uses: MongoCaleb/pr-description-action@master
+        with:
+          regex: "<!-- start insert-links -->.*<!-- end insert-links -->"
+          appendContentOnMatchOnly: true
+          regexFlags: is
+          content: "<!-- start insert-links -->\n${{ steps.build_page_links.outputs.staging_links }}\n<!-- end insert-links -->"
+          token: ${{ secrets.GITHUB_TOKEN }}

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/mongoclient.txt

@@ -97,6 +97,77 @@ instance on port ``27017`` of ``localhost``:
    uri = "mongodb://localhost:27017/"
    client = MongoClient(uri)
 
+The following table describes the positional parameters that the ``MongoClient()``
+constructor accepts. All parameters are optional.
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Parameter
+     - Description
+
+   * - ``host``
+     - The hostname, IP address, or Unix domain socket path of the MongoDB deployment.
+       If your application connects to a replica set or sharded cluster, you can specify
+       multiple hostnames or IP addresses in a Python list.
+       
+       If you pass a literal IPv6 address, you must enclose the address in square brackets
+       (``[ ]``). For example, pass the value ``[::1]`` to connect to localhost.
+
+       {+driver-short+} doesn't support :wikipedia:`multihomed <Multihoming>` and
+       :wikipedia:`round-robin DNS <Round-robin_DNS>` addresses.
+
+       **Data type:** ``Union[str, Sequence[str]]``
+       **Default value:** ``"localhost"``
+
+   * - ``port``
+     - The port number {+mdb-server+} is running on.
+
+       You can include the port number in the ``host`` argument
+       instead of using this parameter.
+
+       **Data type:** ``int``
+       **Default value:** ``27017``
+
+   * - ``document_class``
+     - The default class that the client uses to decode BSON documents returned by queries.
+       This parameter supports the ``bson.raw_bson.RawBSONDocument`` type, as well as
+       subclasses of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``.
+       
+       If you specify ``bson.son.SON`` as the document class, you must also specify types
+       for the key and value.
+
+       **Data type:** ``Type[_DocumentType]``
+
+   * - ``tz_aware``
+     - If this parameter is ``True``, the client treats ``datetime`` values as aware.
+       Otherwise, it treats them as naive.
+
+       For more information about aware and naive ``datetime`` values, see
+       `datetime <https://docs.python.org/3/library/datetime.html>`__ in the Python
+       documentation.
+
+       **Data type:** ``bool``
+
+   * - ``connect``
+     - If this parameter is ``True``, the client begins connecting to MongoDB
+       in the background immediately after you create it. If this parameter is ``False``,
+       the client connects to MongoDB when it performs the first database operation.
+       
+       If your application is running in a
+       :wikipedia:`function-as-a-service (FaaS) <Function_as_a_service>`
+       environment, the default value is ``False``. Otherwise, the default value is ``True``.
+
+       **Data type:** ``bool``
+
+   * - ``type_registry``
+     - An instance of the ``TypeRegistry`` class to enable encoding and decoding of
+       custom types. For more information about encoding and decoding custom types,
+       see :ref:`pymongo-custom-types`.
+
+       **Data type:** `TypeRegistry <{+api-root+}bson/codec_options.html#bson.codec_options.TypeRegistry>`__
+
 .. tip:: Reusing Your Client
 
    Because each ``MongoClient`` object represents a pool of connections to the
@@ -105,6 +176,28 @@ instance on port ``27017`` of ``localhost``:
    a process, the child process *does* need its own ``MongoClient`` object.
    To learn more, see the :ref:`FAQ <pymongo-faq>` page.
 
+Type Hints
+----------
+
+If you're using Python v3.5 or later, you can add type hints to your Python code.
+
+The following code example shows how to declare a type hint for a ``MongoClient``
+object:
+
+.. code-block:: python
+
+   client: MongoClient = MongoClient()
+
+In the previous example, the code doesn't specify a type for the documents that the
+``MongoClient`` object will work with. To specify a document type,
+include the ``Dict[str, Any]`` type when you
+create the ``MongoClient`` object, as shown in the following example:
+
+.. code-block:: python
+
+   from typing import Any, Dict
+   client: MongoClient[Dict[str, Any]] = MongoClient()
+
 API Documentation
 -----------------