Merge branch 'master' into DOCSP-48895

Author: rachel-mack

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 4.11 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 4.12 master
 
 symlink: current -> master
 
@@ -9,7 +9,7 @@ raw: ${prefix}/stable -> ${base}/current/
 raw: ${prefix}/master -> ${base}/upcoming/
 
 # temp redirects until DOP deletes unversioned URLs
-raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/download-and-install/
+raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/
 raw: ${prefix}/compatibility/ -> ${base}/current/compatibility/
 raw: ${prefix}/security/enterprise-authentication/ -> ${base}/current/security/authentication/
 raw: ${prefix}/faq/ -> ${base}/current/
@@ -18,6 +18,7 @@ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/
 raw: ${prefix}/get-started/create-a-deployment/ -> ${base}/current/get-started/
 raw: ${prefix}/get-started/create-a-connection-string/ -> ${base}/current/get-started/
 raw: ${prefix}/get-started/connect-to-mongodb/ -> ${base}/current/get-started/
+raw: ${prefix}/get-started/run-sample-query/ -> ${base}/current/get-started/
 raw: ${prefix}/get-started/next-steps/ -> ${base}/current/get-started/
 raw: ${prefix}/connect/csot/ -> ${base}/current/connect/connection-options/csot/
 raw: ${prefix}/connect/network-compression/ -> ${base}/current/connect/connection-options/network-compression/
@@ -90,7 +91,6 @@ raw: ${prefix}/reference/previous-versions/ -> ${base}/current/reference/previou
 raw: ${prefix}/tools/ -> ${base}/current/integrations/
 raw: ${prefix}/upgrade/ -> ${base}/current/reference/upgrade/
 raw: ${prefix}/write-operations/ -> ${base}/current/crud/
-raw: ${prefix}/get-started/connect-to-mongodb -> ${base}/current/get-started/run-sample-query/
 raw: ${prefix}/work-with-indexes/ -> ${base}/current/indexes/
 raw: ${prefix}/indexes/single-field-index/ -> ${base}/current/indexes/
 raw: ${prefix}/indexes/compound-index/ -> ${base}/current/indexes/
@@ -121,6 +121,7 @@ raw: ${prefix}/security/authentication/kerberos/ -> ${base}/current/security/aut
 [*-master]: ${prefix}/${version}/get-started/create-a-deployment/ -> ${base}/${version}/get-started/
 [*-master]: ${prefix}/${version}/get-started/create-a-connection-string/ -> ${base}/${version}/get-started/
 [*-master]: ${prefix}/${version}/get-started/connect-to-mongodb/ -> ${base}/${version}/get-started/
+[*-master]: ${prefix}/${version}/get-started/run-sample-query/ -> ${base}/${version}/get-started/
 [*-master]: ${prefix}/${version}/get-started/next-steps/ -> ${base}/${version}/get-started/
 [*-master]: ${prefix}/${version}/connect/csot/ -> ${base}/${version}/connect/connection-options/csot/
 [*-master]: ${prefix}/${version}/connect/network-compression/ -> ${base}/${version}/connect/connection-options/network-compression/
@@ -156,7 +157,6 @@ raw: ${prefix}/security/authentication/kerberos/ -> ${base}/current/security/aut
 [*-master]: ${prefix}/${version}/tools/ -> ${base}/${version}/integrations/
 [*-master]: ${prefix}/${version}/upgrade/ -> ${base}/${version}/reference/upgrade/
 [*-master]: ${prefix}/${version}/write-operations/ -> ${base}/${version}/crud/
-[*-master]: ${prefix}/${version}/get-started/connect-to-mongodb -> ${base}/${version}/get-started/run-sample-query/
 [*-master]: ${prefix}/${version}/work-with-indexes/ -> ${base}/${version}/indexes/
 
 [*-master]: ${prefix}/${version}/indexes/single-field-index/ -> ${base}/${version}/indexes/

source/connect/connection-options.txt

@@ -16,6 +16,7 @@ Specify Connection Options
 
 .. meta::
    :keywords: connection string, URI, server, Atlas, settings, configure
+   :description: Explore how to configure MongoDB connection options in PyMongo using connection URIs or `MongoClient` arguments, covering compression, timeouts, and authentication.
 
 .. toctree::
    :titlesonly:

source/connect/connection-targets.txt

@@ -10,6 +10,7 @@ Choose a Connection Target
 
 .. meta::
    :keywords: connection string, URI, server, settings, client, load balancing, srv, dns
+   :description: Learn how to connect to different MongoDB deployments using PyMongo, including Atlas, local deployments, and replica sets, with connection string examples.
 
 .. contents:: On this page
    :local:
@@ -163,6 +164,10 @@ tab to see the corresponding code:
          uri = "mongodb://host1:27017/?replicaSet=sampleRS"
          client = AsyncMongoClient(uri)
 
+.. note:: Replica Set in Docker
+
+   .. sharedinclude:: dbx/docker-replica-set.rst
+
 {+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

source/connect/mongoclient.txt

@@ -10,6 +10,7 @@ Create a MongoClient
 
 .. meta::
    :keywords: connection string, URI, server, Atlas, settings, client
+   :description: Learn how to create a `MongoClient` in PyMongo to connect to a MongoDB deployment using a connection URI and customize connection behavior.
 
 .. contents:: On this page
    :local:

source/data-formats.txt

@@ -16,6 +16,7 @@ Specialized Data Formats
 
 .. meta::
    :keywords: bson, uuid, date, time 
+   :description: Explore how to use specialized data formats in PyMongo, including BSON, Extended JSON, custom types, datetime objects, and UUIDs.
 
 .. toctree::
    :titlesonly:

source/data-formats/custom-types.txt

@@ -16,6 +16,7 @@ Custom Types
 
 .. meta::
    :keywords: bson, uuid, date, time 
+   :description: Learn how to use PyMongo to encode and decode custom types, including defining type codecs, using type registries, and implementing fallback encoders.
 
 .. toctree::
    :titlesonly:

source/data-formats/dates-and-times.txt

@@ -15,6 +15,7 @@ Dates and Times
 
 .. meta::
    :keywords: convert, span, central, mountain, pacific, eastern, calendar 
+   :description: Learn how to handle Python `datetime` objects in PyMongo, including storing, retrieving, and managing time zones and out-of-range dates.
 
 Overview
 --------

source/data-formats/uuid.txt

@@ -15,6 +15,7 @@ Universally Unique IDs (UUIDs)
 
 .. meta::
    :keywords: encode, decode, bson, binary, code examples
+   :description: Learn how to use PyMongo's UuidRepresentation option to handle UUIDs for cross-language compatibility in MongoDB applications.
 
 Overview
 --------

source/databases-collections.txt

@@ -16,6 +16,7 @@ Databases and Collections
 
 .. meta::
    :keywords: table, row, organize, storage
+   :description: Learn how to manage MongoDB databases and collections using PyMongo, including accessing, creating, and deleting collections, and configuring read and write operations.
 
 Overview
 --------

source/includes/language-compatibility-table-pymongo.rst

@@ -27,7 +27,7 @@ CPython
      - CPython 3.5
      - CPython 3.4
 
-   * - 4.11
+   * - 4.11 to 4.12
      - ✓ 
      - ✓ 
      - ✓ 
@@ -199,7 +199,7 @@ PyPy
      - PyPy3.6
      - PyPy3.5
 
-   * - 4.11
+   * - 4.11 to 4.12
      - ✓ 
      -
      -

source/includes/pymongo-async-experimental.rst

@@ -1,7 +1,7 @@
 .. important::
 
-   The {+driver-async+} driver is experimental and should not be used in
-   production environments. Classes, methods, and behaviors described in this
-   guide might change prior to the full release. If you encounter any
-   issues with {+driver-async+}, you can learn how to report them on the
-   :ref:`pymongo-issues-help` page.
+   The {+driver-async+} driver is experimental. We do **not**
+   recommend using it in production environments. Classes, methods, and
+   behaviors described in this guide might change before the production release.
+   If you encounter any issues with {+driver-async+}, you can learn how to
+   report them on the :ref:`pymongo-issues-help` page.

source/index.txt

@@ -9,6 +9,7 @@ MongoDB {+driver-short+} Documentation
 
 .. meta::
    :keywords: home
+   :description: Explore the features and usage of the PyMongo Driver for Python, including installation, connection setup, data operations, and transitioning to PyMongo Async.
 
 .. toctree::
 

source/issues-and-help.txt

@@ -16,6 +16,7 @@ Issues & Help
 
 .. meta::
    :keywords: suggestion, github, python
+   :description: Find support for PyMongo through the MongoDB Community Forums, report bugs or request features via JIRA, and contribute to the driver with pull requests.
 
 We're glad to have such a vibrant community of {+driver-short+}
 users. We recommend seeking support for general

source/reference.txt

@@ -12,4 +12,13 @@ Reference
    Compatibility </reference/compatibility>
    Upgrade Guides </reference/upgrade>
    Migrate to PyMongo Async </reference/migration>
-   Previous Versions </reference/previous-versions>
+   Previous Versions </reference/previous-versions>
+
+To find information about versioning, upgrading your driver, and migrating to
+the asynchronous driver, see the following pages:
+
+ - :ref:`Release Notes <pymongo-release-notes>`
+ - :ref:`Compatibility <pymongo-compatibility>`
+ - :ref:`Upgrade Guides <pymongo-upgrade>`
+ - :ref:`Migrate to PyMongo Async <pymongo-async-migration>`
+ - :ref:`Previous Versions <pymongo-previous-versions>`

source/reference/migration.txt

@@ -61,9 +61,12 @@ Migrate From Motor
 
 .. warning:: Motor Deprecation
 
-   Motor will be deprecated one year after the production release of the {+driver-async+}
-   driver. We strongly recommend that Motor users migrate to the {+driver-async+} driver while
-   Motor is still supported.
+   The {+driver-async+} driver is experimental. We do **not** recommend using it
+   in production environments.
+   
+   Motor will be deprecated one year after the **production release** of the
+   {+driver-async+} driver. We strongly recommend that Motor users migrate to
+   the {+driver-async+} driver while Motor is still supported.
 
 The {+driver-async+} driver functions similarly to the Motor library, but allows
 for improved latency and throughput due to directly using Python Asyncio instead

source/reference/release-notes.txt

@@ -20,6 +20,7 @@ Release Notes
 
 Learn what's new in:
 
+* :ref:`Version 4.12 <version-4.12>`
 * :ref:`Version 4.11 <version-4.11>`
 * :ref:`Version 4.10 <version-4.10>`
 * :ref:`Version 4.9 <version-4.9>`
@@ -37,6 +38,33 @@ version of {+driver-short+} will raise the minimum {+mdb-server+} version from
 4.0 to 4.2. {+driver-short+} will no longer support {+mdb-server+} 4.0. To learn
 how to upgrade your driver version, see the :ref:`pymongo-upgrade` guide.
 
+.. _version-4.12:
+
+What's New in 4.12
+------------------
+
+The {+driver-short+} v4.12 release includes the following new features:
+
+- Adds support for configuring DEK cache lifetime by using the ``key_expiration_ms``
+  argument to ``AutoEncryptionOpts``.
+- Adds support for ``$lookup`` in CSFLE and QE for {+mdb-server+} 8.1 and later.
+- Adds the ``gridfs.asynchronous.grid_file.AsyncGridFSBucket.rename_by_name()`` and
+  ``gridfs.grid_file.GridFSBucket.rename_by_name()`` methods. You can use these methods for
+  more performant renaming of files with multiple revisions.
+- Adds the ``gridfs.asynchronous.grid_file.AsyncGridFSBucket.delete_by_name()`` and
+  ``gridfs.grid_file.GridFSBucket.delete_by_name()`` methods. You can use these methods for
+  more performant deletion of files with multiple revisions.
+- ``AsyncMongoClient`` objects no longer perform DNS resolution for ``mongodb+srv://``
+  connection strings on creation. To avoid blocking the ``asyncio`` loop, {+driver-short+}
+  now defers the resolution until the client is first connected.
+- Adds index hinting support to the ``pymongo.asynchronous.collection.AsyncCollection.distinct()``
+  and ``pymongo.collection.Collection.distinct()`` methods.
+- Deprecates the ``hedge`` parameter for the ``PrimaryPreferred``, ``Secondary``,
+  ``SecondaryPreferred``, and ``Nearest`` read preferences. Support for ``hedge`` will be
+  removed in {+driver-short+} v5.0.
+- Removes PyOpenSSL support from the {+driver-async+} driver.
+- Allows valid SRV hostnames with fewer than 3 parts.
+
 .. _version-4.11:
 
 What's New in 4.11

source/security/authentication.txt

@@ -18,6 +18,7 @@ Authentication Mechanisms
 
 .. meta::
    :keywords: community, security
+   :description: Learn how to authenticate to MongoDB using various authentication mechanisms compatible with different MongoDB Server editions.
 
 .. toctree::
    :caption: Authentication

source/security/in-use-encryption.txt

@@ -17,6 +17,7 @@ In-Use Encryption
 
 .. meta::
    :keywords: qe, csfle, field level encryption
+   :description: Encrypt specific document fields using PyMongo's in-use encryption to protect sensitive data before sending it to MongoDB.
 
 Overview
 --------