PYTHON-927 - Document the non-static nature of MongoClient.nodes

Author: behackett

pymongo/mongo_client.py

@@ -555,10 +555,14 @@ def max_pool_size(self):
 
  @property
  def nodes(self):
- """List of all connected servers.
-
- Nodes are either specified when this instance was created,
- or discovered through the replica set discovery mechanism.
+ """Set of all currently connected servers.
+
+ .. warning:: When connected to a replica set the value of :attr:`nodes`
+ can change over time as :class:`MongoClient`'s view of the replica
+ set changes. :attr:`nodes` can also be an empty set when
+ :class:`MongoClient` is first instantiated and hasn't yet connected
+ to any servers, or a network partition causes it to lose connection
+ to all servers.
  """
  description = self._topology.description
  return frozenset(s.address for s in description.known_servers)