DOCSP-36984 Connection Options (#2)

Author: jordan-smith721

source/fundamentals/connection/connection-options.txt

@@ -1,86 +1,111 @@
 .. uses high-availability.rst
 
+.. _pymongo-connection-options:
+
+==================
+Connection Options
+==================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connect
+
+On this page, you can learn about connection options that you can configure with
+your ``MongoClient``.
+
 .. _secondary-reads:
 
 Secondary Reads
-~~~~~~~~~~~~~~~
+---------------
 
-By default an instance of MongoClient sends queries to
-the primary member of the replica set. To use secondaries for queries
-we have to change the read preference:
+By default, an instance of ``MongoClient`` sends queries to
+the primary member of the replica set. To use secondary members for queries instead, change
+the read preference as shown in the following example:
 
 .. code-block:: python
 
-  >>> client = MongoClient(
-  ...     'localhost:27017',
-  ...     replicaSet='foo',
-  ...     readPreference='secondaryPreferred')
-  >>> client.read_preference
-  SecondaryPreferred(tag_sets=None)
+   >>> client = MongoClient(
+   ...     'localhost:27017',
+   ...     replicaSet='foo',
+   ...     readPreference='secondaryPreferred')
+   >>> client.read_preference
+   SecondaryPreferred(tag_sets=None)
 
-Now all queries will be sent to the secondary members of the set. If there are
-no secondary members the primary will be used as a fallback. If you have
-queries you would prefer to never send to the primary you can specify that
+Now the ``MongoClient`` sends all queries to the secondary members of the replica set. If there are
+no secondary members, the client uses the primary member as a fallback. If you have
+queries you would prefer to never send to the primary, you can specify that
 using the ``secondary`` read preference.
 
---------
-
 .. _health-monitoring:
 
 Health Monitoring
-'''''''''''''''''
+-----------------
 
-When MongoClient is initialized it launches background threads to
-monitor the replica set for changes in:
+When you initialize a ``MongoClient``, it launches background threads to
+monitor the replica set for the following changes:
 
-* Health: detect when a member goes down or comes up, or if a different member
-  becomes primary
-* Configuration: detect when members are added or removed, and detect changes
-  in members' tags
-* Latency: track a moving average of each member's ping time
+- Health: Detect when a member goes down or comes up, or if a different member
+  becomes primary.
+- Configuration: Detect when members are added or removed, and detect changes
+  in members' tags.
+- Latency: Track a moving average of each member's ping time.
 
-Replica-set monitoring ensures queries are continually routed to the proper
+Replica-set monitoring ensures that queries are continually routed to the proper
 members as the state of the replica set changes.
 
 .. _mongos-load-balancing:
 
-mongos Load Balancing
----------------------
+``mongos`` Load Balancing
+-------------------------
 
-An instance of ``~pymongo.mongo_client.MongoClient`` can be configured
-with a list of addresses of mongos servers:
+You can configure an instance of ``~pymongo.mongo_client.MongoClient``
+with a list of ``mongos`` server addresses:
 
 .. code-block:: python
 
    >> client = MongoClient('mongodb://host1,host2,host3')
 
-Each member of the list must be a single mongos server. Multihomed and round
+Each member of the list must be a single ``mongos`` server. Multi-homed and round
 robin DNS addresses are **not** supported. The client continuously
-monitors all the mongoses' availability, and its network latency to each.
+monitors the availability of all ``mongos`` servers. It also monitors its
+network latency to each server.
 
-PyMongo distributes operations evenly among the set of mongoses within its
+PyMongo distributes operations evenly among the set of ``mongos`` servers within its
 ``localThresholdMS`` (similar to how it distributes reads to secondaries
-in a replica set). By default the threshold is 15 ms.
+in a replica set). By default, the threshold is 15 ms.
 
-The lowest-latency server, and all servers with latencies no more than
-``localThresholdMS`` beyond the lowest-latency server's, receive
-operations equally. For example, if we have three mongoses:
+The server with the lowest latency, and all servers with latencies no more than
+``localThresholdMS`` beyond the server with the lowest latency, receive
+operations equally. For example, consider the following three ``mongos`` servers:
 
 - host1: 20 ms
 - host2: 35 ms
 - host3: 40 ms
 
-By default the ``localThresholdMS`` is 15 ms, so PyMongo uses host1 and host2
-evenly. It uses host1 because its network latency to the driver is shortest. It
-uses host2 because its latency is within 15 ms of the lowest-latency server's.
-But it excuses host3: host3 is 20ms beyond the lowest-latency server.
+By default, the ``localThresholdMS`` is 15 ms, so PyMongo uses "host1" and "host2"
+evenly. It uses "host1" because its network latency to the driver is shortest. It
+uses "host2" because its latency is within 15 ms of the server with the lowest latency.
+PyMongo doesn't use "host3" because its latency is 20 ms beyond the server with the
+lowest latency.
 
-If we set ``localThresholdMS`` to 30 ms all servers are within the threshold:
+To ensure that all servers are within the threshold, set ``localThresholdMS`` to 30
+ms as shown in the following example:
 
 .. code-block:: python
 
    >> client = MongoClient('mongodb://host1,host2,host3/?localThresholdMS=30')
 
-.. warning:: Do **not** connect PyMongo to a pool of mongos instances through a
-  load balancer. A single socket connection must always be routed to the same
-  mongos instance for proper cursor support.
+.. warning:: 
+  
+   Do **not** connect PyMongo to a pool of ``mongos`` instances through a
+   load balancer. A single socket connection must always route to the same
+   ``mongos`` instance for proper cursor support.