Use Mongo(ReplicaSet)Client in examples PYTHON-423

doc/examples/aggregation.rst

@@ -7,8 +7,8 @@ group method.
 
 .. testsetup::
 
-  from pymongo import Connection
-  connection = Connection()
+  from pymongo import MongoClient
+  connection = MongoClient()
   connection.drop_database('aggregation_example')
 
 Setup
@@ -18,8 +18,8 @@ aggregations on:
 
 .. doctest::
 
-  >>> from pymongo import Connection
-  >>> db = Connection().aggregation_example
+  >>> from pymongo import MongoClient
+  >>> db = MongoClient().aggregation_example
   >>> db.things.insert({"x": 1, "tags": ["dog", "cat"]})
   ObjectId('...')
   >>> db.things.insert({"x": 2, "tags": ["cat"]})

doc/examples/custom_type.rst

@@ -15,8 +15,8 @@ We'll start by getting a clean database to use for the example:
 
 .. doctest::
 
-  >>> from pymongo.connection import Connection
-  >>> connection = Connection()
+  >>> from pymongo.mongo_client import MongoClient
+  >>> connection = MongoClient()
   >>> connection.drop_database("custom_type_example")
   >>> db = connection.custom_type_example
 
@@ -119,6 +119,7 @@ After doing so we can save and restore :class:`Custom` instances seamlessly:
 .. doctest::
 
   >>> db.test.remove() # remove whatever has already been saved
+  {...}
   >>> db.test.insert({"custom": Custom(5)})
   ObjectId('...')
   >>> db.test.find_one()
@@ -198,6 +199,7 @@ new manipulator:
 .. doctest::
 
   >>> db.test.remove()
+  {...}
   >>> db.add_son_manipulator(TransformToBinary())
 
 After doing so we can save and restore :class:`Custom` instances

doc/examples/geo.rst

@@ -3,8 +3,8 @@ Geospatial Indexing Example
 
 .. testsetup::
 
-  from pymongo import Connection
-  connection = Connection()
+  from pymongo import MongoClient
+  connection = MongoClient()
   connection.drop_database('geo_example')
 
 This example shows how to create and use a :data:`~pymongo.GEO2D`
@@ -22,8 +22,8 @@ Creating a geospatial index in pymongo is easy:
 
 .. doctest::
 
-  >>> from pymongo import Connection, GEO2D
-  >>> db = Connection().geo_example
+  >>> from pymongo import MongoClient, GEO2D
+  >>> db = MongoClient().geo_example
   >>> db.places.create_index([("loc", GEO2D)])
   u'loc_2d'
 

doc/examples/gevent.rst

@@ -3,12 +3,12 @@ Gevent
 
 .. testsetup::
 
-  from pymongo import Connection, ReplicaSetConnection
+  from pymongo import MongoClient, MongoReplicaSetClient
 
 PyMongo supports `Gevent <http://www.gevent.org/>`_. Primarily, this means that
-:meth:`~pymongo.connection.Connection.start_request()` can ensure that the
+:meth:`~pymongo.mongo_client.MongoClient.start_request()` can ensure that the
 current greenlet (not merely the current thread) uses the same socket for all
-operations until :meth:`~pymongo.connection.Connection.end_request()` is called.
+operations until :meth:`~pymongo.mongo_client.MongoClient.end_request()` is called.
 See the :doc:`requests documentation <requests>` for details on requests in
 PyMongo.
 
@@ -25,7 +25,7 @@ socket exclusively by default.
 .. doctest::
 
   >>> from gevent import monkey; monkey.patch_all()
-  >>> connection = Connection()
+  >>> connection = MongoClient()
 
 Make sure you're using the latest version of Gevent to ensure that
 thread-locals are patched to act like greenlet-locals, and be careful to call
@@ -37,33 +37,33 @@ Using Gevent With Threads
 If you need to use standard Python threads in the same process as Gevent and
 greenlets, you only need to run ``monkey.patch_socket()``, rather than
 ``monkey.patch_all()``, and create a
-:class:`~pymongo.connection.Connection` with ``use_greenlets=True``.
-The :class:`~pymongo.connection.Connection` will use a special greenlet-aware
+:class:`~pymongo.mongo_client.MongoClient` with ``use_greenlets=True``.
+The :class:`~pymongo.mongo_client.MongoClient` will use a special greenlet-aware
 connection pool that allocates a socket for each greenlet, ensuring consistent
 reads in Gevent.
 
 .. doctest::
 
   >>> from gevent import monkey; monkey.patch_socket()
-  >>> connection = Connection(use_greenlets=True)
+  >>> connection = MongoClient(use_greenlets=True)
 
-An instance of :class:`~pymongo.replica_set_connection.ReplicaSetConnection`
+An instance of :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`
 created with ``use_greenlets=True`` will also use a greenlet-aware pool.
 Additionally, it will use a background greenlet instead of a background thread
 to monitor the state of the replica set.
 
-Using :meth:`~pymongo.replica_set_connection.ReplicaSetConnection.start_request()`
+Using :meth:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.start_request()`
 with :class:`~pymongo.read_preferences.ReadPreference` PRIMARY ensures that the
 current greenlet uses the same socket for all operations until a call to
 :meth:`end_request()`.
 
 You must `install Gevent <http://gevent.org/>`_ to use
-:class:`~pymongo.replica_set_connection.ReplicaSetConnection`
+:class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`
 with ``use_greenlets=True``
 
 .. doctest::
 
   >>> from gevent import monkey; monkey.patch_socket()
-  >>> rsc = ReplicaSetConnection(
+  >>> rsc = MongoReplicaSetClient(
   ...     'mongodb://localhost:27017,localhost:27018,localhost:27019',
   ...     replicaSet='repl0', use_greenlets=True)

doc/examples/gridfs.rst

@@ -3,8 +3,8 @@ GridFS Example
 
 .. testsetup::
 
-  from pymongo import Connection
-  connection = Connection()
+  from pymongo import MongoClient
+  connection = MongoClient()
   connection.drop_database('gridfs_example')
 
 This example shows how to use :mod:`gridfs` to store large binary
@@ -23,10 +23,10 @@ We start by creating a :class:`~gridfs.GridFS` instance to use:
 
 .. doctest::
 
-  >>> from pymongo import Connection
+  >>> from pymongo import MongoClient
   >>> import gridfs
   >>>
-  >>> db = Connection().gridfs_example
+  >>> db = MongoClient().gridfs_example
   >>> fs = gridfs.GridFS(db)
 
 Every :class:`~gridfs.GridFS` instance is created with and will

doc/examples/high_availability.rst

@@ -63,8 +63,8 @@ To initialize the set we need to connect to a single node and run the
 initiate command. Since we don't have a primary yet, we'll need to
 tell PyMongo that it's okay to connect to a slave/secondary::
 
-  >>> from pymongo import Connection
-  >>> c = Connection("morton.local:27017", slave_okay=True)
+  >>> from pymongo import MongoClient
+  >>> c = MongoClient("morton.local:27017", slave_okay=True)
 
 .. note:: We could have connected to any of the other nodes instead,
    but only the node we initiate from is allowed to contain any
@@ -87,22 +87,22 @@ Connecting to a Replica Set
 The initial connection as made above is a special case for an
 uninitialized replica set. Normally we'll want to connect
 differently. A connection to a replica set can be made using the
-normal :meth:`~pymongo.connection.Connection` constructor, specifying
+normal :meth:`~pymongo.mongo_client.MongoClient` constructor, specifying
 one or more members of the set. For example, any of the following
 will create a connection to the set we just created::
 
-  >>> Connection("morton.local", replicaset='foo')
-  Connection([u'morton.local:27019', 'morton.local:27017', u'morton.local:27018'])
-  >>> Connection("morton.local:27018", replicaset='foo')
-  Connection([u'morton.local:27019', u'morton.local:27017', 'morton.local:27018'])
-  >>> Connection("morton.local", 27019, replicaset='foo')
-  Connection(['morton.local:27019', u'morton.local:27017', u'morton.local:27018'])
-  >>> Connection(["morton.local:27018", "morton.local:27019"])
-  Connection(['morton.local:27019', u'morton.local:27017', 'morton.local:27018'])
-  >>> Connection("mongodb://morton.local:27017,morton.local:27018,morton.local:27019")
-  Connection(['morton.local:27019', 'morton.local:27017', 'morton.local:27018'])
+  >>> MongoClient("morton.local", replicaset='foo')
+  MongoClient([u'morton.local:27019', 'morton.local:27017', u'morton.local:27018'])
+  >>> MongoClient("morton.local:27018", replicaset='foo')
+  MongoClient([u'morton.local:27019', u'morton.local:27017', 'morton.local:27018'])
+  >>> MongoClient("morton.local", 27019, replicaset='foo')
+  MongoClient(['morton.local:27019', u'morton.local:27017', u'morton.local:27018'])
+  >>> MongoClient(["morton.local:27018", "morton.local:27019"])
+  MongoClient(['morton.local:27019', u'morton.local:27017', 'morton.local:27018'])
+  >>> MongoClient("mongodb://morton.local:27017,morton.local:27018,morton.local:27019")
+  MongoClient(['morton.local:27019', 'morton.local:27017', 'morton.local:27018'])
 
-The nodes passed to :meth:`~pymongo.connection.Connection` are called
+The nodes passed to :meth:`~pymongo.mongo_client.MongoClient` are called
 the *seeds*. If only one host is specified the `replicaset` parameter
 must be used to indicate this isn't a connection to a single node.
 As long as at least one of the seeds is online, the driver will be able
@@ -118,7 +118,7 @@ can't happen completely transparently, however. Here we'll perform an
 example failover to illustrate how everything behaves. First, we'll
 connect to the replica set and perform a couple of basic operations::
 
-  >>> db = Connection("morton.local", replicaSet='foo').test
+  >>> db = MongoClient("morton.local", replicaSet='foo').test
   >>> db.test.save({"x": 1})
   ObjectId('...')
   >>> db.test.find_one()
@@ -160,29 +160,29 @@ the operation will succeed::
   >>> db.connection.port
   27018
 
-ReplicaSetConnection
-~~~~~~~~~~~~~~~~~~~~
+MongoReplicaSetClient
+~~~~~~~~~~~~~~~~~~~~~
 
-Using a :class:`~pymongo.replica_set_connection.ReplicaSetConnection` instead
-of a simple :class:`~pymongo.connection.Connection` offers two key features:
+Using a :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient` instead
+of a simple :class:`~pymongo.mongo_client.MongoClient` offers two key features:
 secondary reads and replica set health monitoring. To connect using
-`ReplicaSetConnection` just provide a host:port pair and the name of the
-replica set::
+:class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient` just provide a
+host:port pair and the name of the replica set::
 
-  >>> from pymongo import ReplicaSetConnection
-  >>> ReplicaSetConnection("morton.local:27017", replicaSet='foo')
-  ReplicaSetConnection([u'morton.local:27019', u'morton.local:27017', u'morton.local:27018'])
+  >>> from pymongo import MongoReplicaSetClient
+  >>> MongoReplicaSetClient("morton.local:27017", replicaSet='foo')
+  MongoReplicaSetClient([u'morton.local:27019', u'morton.local:27017', u'morton.local:27018'])
 
 .. _secondary-reads:
 
 Secondary Reads
 '''''''''''''''
 
-By default an instance of ReplicaSetConnection will only send queries to
+By default an instance of MongoReplicaSetClient will only send queries to
 the primary member of the replica set. To use secondaries for queries
 we have to change the :class:`~pymongo.read_preference.ReadPreference`::
 
-  >>> db = ReplicaSetConnection("morton.local:27017", replicaSet='foo').test
+  >>> db = MongoReplicaSetClient("morton.local:27017", replicaSet='foo').test
   >>> from pymongo.read_preference import ReadPreference
   >>> db.read_preference = ReadPreference.SECONDARY_PREFERRED
 
@@ -226,42 +226,42 @@ and **secondary_acceptable_latency_ms**.
 
 Replica-set members can be `tagged
 <http://www.mongodb.org/display/DOCS/Data+Center+Awareness>`_ according to any
-criteria you choose. By default, ReplicaSetConnection ignores tags when
+criteria you choose. By default, MongoReplicaSetClient ignores tags when
 choosing a member to read from, but it can be configured with the ``tag_sets``
 parameter. ``tag_sets`` must be a list of dictionaries, each dict providing tag
-values that the replica set member must match. ReplicaSetConnection tries each
+values that the replica set member must match. MongoReplicaSetClient tries each
 set of tags in turn until it finds a set of tags with at least one matching
 member. For example, to prefer reads from the New York data center, but fall
 back to the San Francisco data center, tag your replica set members according
-to their location and create a ReplicaSetConnection like so:
+to their location and create a MongoReplicaSetClient like so:
 
-  >>> rsc = ReplicaSetConnection(
+  >>> rsc = MongoReplicaSetClient(
   ...     "morton.local:27017",
   ...     replicaSet='foo'
   ...     read_preference=ReadPreference.SECONDARY,
   ...     tag_sets=[{'dc': 'ny'}, {'dc': 'sf'}]
   ... )
 
-ReplicaSetConnection tries to find secondaries in New York, then San Francisco,
+MongoReplicaSetClient tries to find secondaries in New York, then San Francisco,
 and raises :class:`~pymongo.errors.AutoReconnect` if none are available. As an
 additional fallback, specify a final, empty tag set, ``{}``, which means "read
 from any member that matches the mode, ignoring tags."
 
 **secondary_acceptable_latency_ms**:
 
-If multiple members match the mode and tag sets, ReplicaSetConnection reads
+If multiple members match the mode and tag sets, MongoReplicaSetClient reads
 from among the nearest members, chosen according to ping time. By default,
 only members whose ping times are within 15 milliseconds of the nearest
 are used for queries. You can choose to distribute reads among members with
 higher latencies by setting ``secondary_acceptable_latency_ms`` to a larger
-number. In that case, ReplicaSetConnection distributes reads among matching
+number. In that case, MongoReplicaSetClient distributes reads among matching
 members within ``secondary_acceptable_latency_ms`` of the closest member's
 ping time.
 
 Health Monitoring
 '''''''''''''''''
 
-When ReplicaSetConnection is initialized it launches a background task to
+When MongoReplicaSetClient is initialized it launches a background task to
 monitor the replica set for changes in:
 
 * Health: detect when a member goes down or comes up, or if a different member
@@ -273,7 +273,7 @@ Replica-set monitoring ensures queries are continually routed to the proper
 members as the state of the replica set changes.
 
 It is critical to call
-:meth:`~pymongo.replica_set_connection.ReplicaSetConnection.close` to terminate
+:meth:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.close` to terminate
 the monitoring task before your process exits.
 
 .. _mongos-high-availability:
@@ -281,7 +281,7 @@ the monitoring task before your process exits.
 High Availability and mongos
 ----------------------------
 
-An instance of :class:`~pymongo.connection.Connection` can be configured
+An instance of :class:`~pymongo.mongo_client.MongoClient` can be configured
 to automatically connect to a different mongos if the instance it is
 currently connected to fails. If a failure occurs, PyMongo will attempt
 to find the nearest mongos to perform subsequent operations. As with a
@@ -290,13 +290,13 @@ an example failover to illustrate how everything behaves. First, we'll
 connect to a sharded cluster, using a seed list, and perform a couple of
 basic operations::
 
-  >>> db = Connection('morton.local:30000,morton.local:30001,morton.local:30002').test
+  >>> db = MongoClient('morton.local:30000,morton.local:30001,morton.local:30002').test
   >>> db.test.save({"x": 1})
   ObjectId('...')
   >>> db.test.find_one()
   {u'x': 1, u'_id': ObjectId('...')}
 
-Each member of the seed list passed to Connection must be a mongos. By checking
+Each member of the seed list passed to MongoClient must be a mongos. By checking
 the host, port, and is_mongos attributes we can see that we're connected to
 *morton.local:30001*, a mongos::