wip

Author: mongoKart

config/redirects

@@ -12,3 +12,4 @@ raw: ${prefix}/master -> ${base}/upcoming/
 raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/download-and-install/
 
 [*-master]: ${prefix}/${version}/security/enterprise-authentication/ -> ${base}/${version}/security/authentication/
+[*-master]: ${prefix}/${version}/faq/ -> ${base}/${version}/

source/connect/mongoclient.txt

@@ -168,13 +168,60 @@ constructor accepts. All parameters are optional.
 
        **Data type:** `TypeRegistry <{+api-root+}bson/codec_options.html#bson.codec_options.TypeRegistry>`__
 
-.. tip:: Reusing Your Client
+Concurrent Execution
+--------------------
 
-   Because each ``MongoClient`` object represents a pool of connections to the
-   database, most applications require only a single instance of
-   ``MongoClient``, even across multiple requests. However, if you fork
-   a process, the child process *does* need its own ``MongoClient`` object.
-   To learn more, see the :ref:`FAQ <pymongo-faq>` page.
+The following sections describe {+driver-short+}'s support for concurrent execution
+mechanisms.
+
+Multithreading
+~~~~~~~~~~~~~~
+
+{+driver-short+} is thread-safe and provides built-in connection pooling
+for threaded applications. 
+Because each ``MongoClient`` object represents a pool of connections to the
+database, most applications require only a single instance of
+``MongoClient``, even across multiple requests.
+
+.. _pymongo-forks:
+
+Multiple Forks
+~~~~~~~~~~~~~~~
+
+{+driver-short+} supports using the ``fork()`` method to create a new process. 
+However, if you fork a process, you must create a new ``MongoClient`` instance in the
+child process.
+
+.. important:: Don't Pass a MongoClient to a Child Process
+
+   If you use the ``fork()`` method to create a new process, don't pass an instance
+   of the ``MongoClient`` class from the parent process to the child process. This creates
+   a high probability of deadlock among ``MongoClient`` instances in the child process.
+   {+driver-short+} tries to issue a warning if this deadlock might occur.
+
+Multiprocessing
+~~~~~~~~~~~~~~~
+
+{+driver-short+} supports the Python ``multiprocessing`` module.
+However, on Unix systems, the multiprocessing module spawns processes by using
+the ``fork()`` method. This carries the same risks described in :ref:`<pymongo-forks>`
+
+To use multiprocessing with {+driver-short+}, write code similar to the following example:
+
+.. code-block:: python
+
+   # Each process creates its own instance of MongoClient.
+   def func():
+       db = pymongo.MongoClient().mydb
+       # Do something with db.
+
+   proc = multiprocessing.Process(target=func)
+   proc.start()
+
+.. important::
+   
+   Do not copy an instance of the ``MongoClient`` class from the parent process to a child
+   process.
 
 Type Hints
 ----------

source/faq.txt

@@ -1,63 +1,4 @@
-.. _pymongo-faq:
-
-Frequently Asked Questions
-==========================
-
-.. contents:: On this page
-   :local:
-   :backlinks: none
-   :depth: 1
-   :class: singlecol
-
-.. facet::
-   :name: genre
-   :values: reference
-
-.. meta::
-   :keywords: errors, problems, help, troubleshoot
-
-Is {+driver-short+} Thread-Safe?
------------------------
-
-Yes. {+driver-short+} is thread-safe and provides built-in connection pooling
-for threaded applications.
-
-.. _pymongo-fork-safe:
-
-Is {+driver-short+} Fork-Safe?
----------------------
-
-No. If you use the ``fork()`` method to create a new process, don't pass an instance
-of the ``MongoClient`` class from the parent process to the child process. This creates
-a high probability of deadlock among ``MongoClient`` instances in the child process.
-Instead, create a new ``MongoClient`` instance in the child process.
-
-.. note::
-   
-   {+driver-short+} tries to issue a warning if this deadlock might occur.
-
-Can I Use {+driver-short+} with Multiprocessing?
----------------------------------------
-
-Yes. However, on Unix systems, the multiprocessing module spawns processes by using
-the ``fork()`` method. This carries the same risks described in :ref:`<pymongo-fork-safe>`
-
-To use multiprocessing with {+driver-short+}, write code similar to the following example:
-
-.. code-block:: python
-
-   # Each process creates its own instance of MongoClient.
-   def func():
-       db = pymongo.MongoClient().mydb
-       # Do something with db.
-
-   proc = multiprocessing.Process(target=func)
-   proc.start()
-
-.. important::
-   
-   Do not copy an instance of the ``MongoClient`` class from the parent process to a child
-   process.
+.. docs-landing/source/languages/python.txt
 
 Can {+driver-short+} Load the Results of a Query as a Pandas DataFrame?
 -----------------------------------------------------------------------
@@ -69,194 +10,6 @@ load MongoDB query result-sets as
 `NumPy ndarrays <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`__, or
 `Apache Arrow Tables <https://arrow.apache.org/docs/python/generated/pyarrow.Table.html>`__.
 
-How Does Connection Pooling Work in {+driver-short+}?
---------------------------------------------
-
-Every ``MongoClient`` instance has a built-in connection pool for each server
-in your MongoDB topology. Connection pools open sockets on demand to
-support concurrent requests to MongoDB in your application.
-
-The maximum size of each connection pool is set by the ``maxPoolSize`` option, which
-defaults to ``100``. If the number of in-use connections to a server reaches
-the value of ``maxPoolSize``, the next request to that server will wait
-until a connection becomes available.
-
-In addition to the sockets needed to support your application's requests,
-each ``MongoClient`` instance opens two more sockets per server
-in your MongoDB topology for monitoring the server's state.
-For example, a client connected to a three-node replica set opens six
-monitoring sockets. If the application uses the default setting for
-``maxPoolSize`` and only queries the primary (default) node, then
-there can be at most ``106`` total connections in the connection pool. If the
-application uses a :ref:`read preference <read-preference>` to query the
-secondary nodes, those connection pools grow and there can be
-``306`` total connections.
-
-To support high numbers of concurrent MongoDB requests
-within one process, you can increase ``maxPoolSize``.
-
-Connection pools are rate-limited. The ``maxConnecting`` option
-determines the number of connections that the pool can create in
-parallel at any time. For example, if the value of ``maxConnecting`` is
-``2``, the third request that attempts to concurrently check out a
-connection succeeds only when one the following cases occurs:
-
-- The connection pool finishes creating a connection and there are fewer
-  than ``maxPoolSize`` connections in the pool.
-- An existing connection is checked back into the pool.
-- The driver's ability to reuse existing connections improves due to
-  rate-limits on connection creation.
-
-You can set the minimum number of concurrent connections to
-each server with the ``minPoolSize`` option, which defaults to ``0``.
-The driver initializes the connection pool with this number of sockets. If
-sockets are closed, causing the total number
-of sockets (both in use and idle) to drop below the minimum, more
-sockets are opened until the minimum is reached.
-
-You can set the maximum number of milliseconds that a connection can
-remain idle in the pool by setting the ``maxIdleTimeMS`` option.
-Once a connection has been idle for ``maxIdleTimeMS``, the connection
-pool removes and replaces it. This option defaults to ``0`` (no limit).
-
-The following default configuration for a ``MongoClient`` works for most
-applications:
-
-.. code-block:: python
-
-   client = MongoClient(host, port)
-
-``MongoClient`` supports multiple concurrent requests. For each process,
-create a client and reuse it for all operations in a process. This
-practice is more efficient than creating a client for each request.
-
-The driver does not limit the number of requests that
-can wait for sockets to become available, and it is the application's
-responsibility to limit the size of its pool to bound queuing
-during a load spike. Requests wait for the amount of time specified in
-the ``waitQueueTimeoutMS`` option, which defaults to ``0`` (no limit).
-
-A request that waits more than the length of time defined by
-``waitQueueTimeoutMS`` for a socket raises a ``ConnectionFailure`` error. Use this
-option if it is more important to bound the duration of operations
-during a load spike than it is to complete every operation.
-
-When ``MongoClient.close()`` is called by any request, the driver
-closes all idle sockets and closes all sockets that are in
-use as they are returned to the pool. Calling ``MongoClient.close()``
-closes only inactive sockets, so you cannot interrupt or terminate
-any ongoing operations by using this method. The driver closes these
-sockets only when the process completes.
-
-For more information, see the :manual:`Connection Pool Overview </administration/connection-pool-overview/>`
-in the {+mdb-server+} documentation.
-
-Why Does {+driver-short+} Add an _id Field to All My Documents?
-------------------------------------------------------
-
-When you use the ``Collection.insert_one()`` method,
-``Collection.insert_many()`` method, or
-``Collection.bulk_write()`` method to insert a document into MongoDB,
-and that document does not
-include an ``_id`` field, {+driver-short+} automatically adds this field for you.
-It also sets the value of the field to an instance of ``ObjectId``.
-
-The following code example inserts a document without an ``_id`` field into MongoDB, then
-prints the document. After it's inserted, the document contains an ``_id`` field whose
-value is an instance of ``ObjectId``.
-
-.. code-block:: python
-
-   >>> my_doc = {'x': 1}
-   >>> collection.insert_one(my_doc)
-   InsertOneResult(ObjectId('560db337fba522189f171720'), acknowledged=True)
-   >>> my_doc
-   {'x': 1, '_id': ObjectId('560db337fba522189f171720')}
-
-{+driver-short+} adds an ``_id`` field in this manner for a few reasons:
-
-- All MongoDB documents must have an ``_id`` field.
-- If {+driver-short+} inserts a document without an ``_id`` field, MongoDB adds one
-  itself, but doesn't report the value back to {+driver-short+} for your application
-  to use.
-- Copying the document before adding the ``_id`` field is
-  prohibitively expensive for most high-write-volume applications.
-
-.. tip::
-   
-   If you don't want {+driver-short+} to add an ``_id`` to your documents, insert only
-   documents that your application has already added an ``_id`` field to.
-
-How Do I Change the Timeout Value for Cursors?
-----------------------------------------------
-
-MongoDB doesn't support custom timeouts for cursors, but you can turn off cursor
-timeouts. To do so, pass the ``no_cursor_timeout=True`` option to
-the ``find()`` method.
-
-How Can I Store ``Decimal`` Instances?
---------------------------------------
-
-MongoDB v3.4 introduced the ``Decimal128`` BSON type, a 128-bit decimal-based
-floating-point value capable of emulating decimal rounding with exact precision.
-{+driver-short+} versions 3.4 and later also support this type.
-Earlier MongoDB versions, however, support only IEEE 754 floating points, equivalent to the
-Python ``float`` type. {+driver-short+} can store ``Decimal`` instances to
-these versions of MongoDB only by converting them to the ``float`` type.
-You must perform this conversion explicitly. 
-
-For more information, see the {+driver-short+} API documentation for
-`decimal128. <https://pymongo.readthedocs.io/en/latest/api/bson/decimal128.html#module-bson.decimal128>`__
-
-Why Does {+driver-short+} Convert ``9.99`` to ``9.9900000000000002``?
----------------------------------------------------------------------
-
-MongoDB represents ``9.99`` as an IEEE floating-point value, which can't
-represent the value precisely. This is also true in some versions of
-Python. In this regard, {+driver-short+} behaves the same way as
-the JavaScript shell, all other MongoDB drivers, and the Python language itself.
-
-Does {+driver-short+} Support Attribute-style Access for Documents?
-----------------------------------------------------------
-
-No. {+driver-short+} doesn't implement this feature, for the following reasons:
-
-1. Adding attributes pollutes the attribute namespace for documents and could
-   lead to subtle bugs or confusing errors when using a key with the
-   same name as a dictionary method.
-
-#. {+driver-short+} uses SON objects instead of regular
-   dictionaries only to maintain key ordering, because the server
-   requires this for certain operations. Adding this feature would
-   complicate the ``SON`` class and could break backwards compatibility
-   if {+driver-short+} ever reverts to using dictionaries.
-
-#. Documents behave just like dictionaries, which makes them relatively simple
-   for new {+driver-short+} users to understand. Changing the behavior of documents
-   adds a barrier to entry for these users.
-
-For more information, see the relevant
-`Jira case. <http://jira.mongodb.org/browse/PYTHON-35>`__
-
-Does {+driver-short+} Support Asynchronous Frameworks?
----------------------------------------------
-
-Yes. For more information, see the :ref:`<pymongo-tools>` guide.
-
-Does {+driver-short+} Work with mod_wsgi?
---------------------------------
-
-Yes. See :ref:`pymongo-mod_wsgi` in the Tools guide.
-
-Does {+driver-short+} Work with PythonAnywhere?
---------------------------------------
-
-No. {+driver-short+} creates Python threads, which
-`PythonAnywhere <https://www.pythonanywhere.com>`__ does not support.
-
-For more information, see
-the relevant `Jira ticket. <https://jira.mongodb.org/browse/PYTHON-1495>`__
-
 How Can I Encode My Documents to JSON?
 --------------------------------------
 
@@ -278,7 +31,6 @@ depend on {+driver-short+} and might offer a performance improvement over
    python-bsonjs works best with {+driver-short+} when using the ``RawBSONDocument``
    type.
 
-
 Does {+driver-short+} Behave Differently in Python 3?
 -----------------------------------------------------
 

source/includes/write/unique-id-note.rst

@@ -0,0 +1,12 @@
+.. note:: _id Field Must Be Unique
+
+   In a MongoDB collection, each document must contain an ``_id`` field
+   with a unique value.
+
+   If you specify a value for the ``_id`` field, you must ensure that the
+   value is unique across the collection. If you don't specify a value,
+   the driver automatically generates a unique ``ObjectId`` value for the field.
+
+   We recommend letting the driver automatically generate ``_id`` values to
+   ensure uniqueness. Duplicate ``_id`` values violate unique index constraints, which
+   causes the driver to return an error. 

source/tools.txt

@@ -274,3 +274,11 @@ This section lists alternatives to {+driver-short+}.
 - `MongoMock <https://github.com/mongomock/mongomock>`__ is a small
   library to help test Python code. It uses {+driver-short+} to interact with MongoDB.
 
+.. note:: {+driver-short+} is Incompatible with PythonAnywhere
+
+   {+driver-short+} creates Python threads, which
+   `PythonAnywhere <https://www.pythonanywhere.com>`__ does not support.
+
+   For more information, see
+   the relevant `Jira ticket. <https://jira.mongodb.org/browse/PYTHON-1495>`__
+

source/write/bulk-write.txt

@@ -67,11 +67,7 @@ The following example creates an instance of ``InsertOne``:
 
 To insert multiple documents, create an instance of ``InsertOne`` for each document.
 
-.. note::
-
-   Duplicate ``_id`` values violate unique index constraints, which causes the
-   driver to return a ``DuplicateKeyError``. To avoid this error, ensure that
-   each document you insert has a unique ``_id`` value.
+.. include:: /includes/write/unique-id-note.rst
 
 Update Operations
 ~~~~~~~~~~~~~~~~~