PYTHON-1110 - Multihomed and round robin DNS addresses are not supported

behackett · behackett · commit 7a64cfc6e724 · 2016-07-05T14:37:39.000-07:00
diff --git a/doc/examples/high_availability.rst b/doc/examples/high_availability.rst
@@ -96,7 +96,9 @@ the following connects to the replica set we just created::
 The addresses passed to :meth:`~pymongo.mongo_client.MongoClient` are called
 the *seeds*. As long as at least one of the seeds is online, MongoClient
 discovers all the members in the replica set, and determines which is the
-current primary and which are secondaries or arbiters.
+current primary and which are secondaries or arbiters. Each seed must be the
+address of a single mongod. Multihomed and round robin DNS addresses are
+**not** supported.
 
 The :class:`~pymongo.mongo_client.MongoClient` constructor is non-blocking:
 the constructor returns immediately while the client connects to the replica
@@ -325,11 +327,12 @@ mongos Load Balancing
 ---------------------
 
 An instance of :class:`~pymongo.mongo_client.MongoClient` can be configured
-with a list of mongos servers:
+with a list of addresses of mongos servers:
 
   >>> client = MongoClient('mongodb://host1,host2,host3')
 
-Each member of the list must be a mongos server. The client continuously
+Each member of the list must be a single mongos server. Multihomed and round
+robin DNS addresses are **not** supported. The client continuously
 monitors all the mongoses' availability, and its network latency to each.
 
 PyMongo distributes operations evenly among the set of mongoses within its
@@ -352,3 +355,7 @@ But it excuses host3: host3 is 20ms beyond the lowest-latency server.
 If we set ``localThresholdMS`` to 30 ms all servers are within the threshold:
 
   >>> 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.
diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py
@@ -107,11 +107,12 @@ def __init__(
           read :ref:`multiprocessing` first.
 
         :Parameters:
-          - `host` (optional): hostname or IP address of the
-            instance to connect to, or a mongodb URI, or a list of
+          - `host` (optional): hostname or IP address of a single mongod or
+            mongos instance to connect to, or a mongodb URI, or a list of
             hostnames / mongodb URIs. If `host` is an IPv6 literal
             it must be enclosed in '[' and ']' characters following
-            the RFC2732 URL syntax (e.g. '[::1]' for localhost)
+            the RFC2732 URL syntax (e.g. '[::1]' for localhost). Multihomed
+            and round robin DNS addresses are **not** supported.
           - `port` (optional): port number on which to connect
           - `document_class` (optional): default class to use for
             documents returned from queries on this client
