Permalink
Browse files

Rename MotorConnection to MotorClient, MotorReplicaSetConnection to M…

…otorReplicaSetClient
  • Loading branch information...
1 parent f662737 commit 3aa4948d13858f3ebf286256c5af3263e3f6eeb5 @ajdavis committed Dec 12, 2012
@@ -8,21 +8,21 @@ Major differences
Creating a connection
---------------------
-PyMongo's :class:`~pymongo.connection.Connection` and
-:class:`~pymongo.replica_set_connection.ReplicaSetConnection` constructors
+PyMongo's :class:`~pymongo.mongo_client.MongoClient` and
+:class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient` constructors
block until they have established a connection to MongoDB. A
-:class:`~motor.MotorConnection` or :class:`~motor.MotorReplicaSetConnection`,
+:class:`~motor.MotorClient` or :class:`~motor.MotorReplicaSetClient`,
however, is created unconnected. One should call
-:meth:`~motor.MotorConnection.open_sync` at the beginning of a Tornado web
+:meth:`~motor.MotorClient.open_sync` at the beginning of a Tornado web
application, before accepting requests:
.. code-block:: python
import motor
- connection = motor.MotorConnection().open_sync()
+ connection = motor.MotorClient().open_sync()
To make a connection asynchronously once the application is running, call
-:meth:`~motor.MotorConnection.open`:
+:meth:`~motor.MotorClient.open`:
.. code-block:: python
@@ -33,7 +33,7 @@ To make a connection asynchronously once the application is running, call
# Use the connection
pass
- motor.MotorConnection().open(connected)
+ motor.MotorClient().open(connected)
Callbacks
---------
@@ -55,15 +55,15 @@ For example, one uses
.. code-block:: python
- db = Connection().test
+ db = MongoClient().test
user = db.users.find_one({'name': 'Jesse'})
print user
But Motor's :meth:`~motor.MotorCollection.find_one` method works asynchronously:
.. code-block:: python
- db = MotorConnection().open_sync().test
+ db = MotorClient().open_sync().test
def got_user(user, error):
if error:
@@ -193,14 +193,14 @@ In PyMongo, you can set a network timeout which causes an
:exc:`~pymongo.errors.AutoReconnect` exception if an operation does not complete
in time::
- db = Connection(socketTimeoutMS=500).test
+ db = MongoClient(socketTimeoutMS=500).test
try:
user = db.users.find_one({'name': 'Jesse'})
print user
except AutoReconnect:
print 'timed out'
-:class:`~motor.MotorConnection` and :class:`~motor.MotorReplicaSetConnection`
+:class:`~motor.MotorClient` and :class:`~motor.MotorReplicaSetClient`
support the same options. The exception isn't raised, instead it's passed to
the callback as the ``error`` parameter, and the ``result`` parameter will be
``None``. Code using `tornado.gen`_ ends up looking very similar to the
@@ -251,7 +251,7 @@ the server. Obviously, this code is improved by `tornado.gen`_::
print result
Motor ignores the ``auto_start_request`` parameter to
-:class:`~motor.MotorConnection` or :class:`~motor.MotorReplicaSetConnection`.
+:class:`~motor.MotorClient` or :class:`~motor.MotorReplicaSetClient`.
.. _tornado.gen: http://www.tornadoweb.org/documentation/gen.html
@@ -352,9 +352,9 @@ GridFS
is_locked
---------
-:meth:`~motor.MotorConnection.is_locked` in Motor is a method requiring a
+:meth:`~motor.MotorClient.is_locked` in Motor is a method requiring a
callback, whereas in PyMongo it is a property of
-:class:`~pymongo.connection.Connection`.
+:class:`~pymongo.mongo_client.MongoClient`.
system_js
---------
@@ -62,7 +62,7 @@ Here's an example of an application that can create and display short messages:
self.write('</ul>')
self.finish()
- db = motor.MotorConnection().open_sync().test
+ db = motor.MotorClient().open_sync().test
application = tornado.web.Application(
[
@@ -11,7 +11,7 @@ Writing a file to GridFS with :meth:`~motor.MotorGridFS.put`
from tornado import gen
import motor
- db = motor.MotorConnection().open_sync().test
+ db = motor.MotorClient().open_sync().test
@gen.engine
def write_file():
@@ -37,7 +37,7 @@ Streaming a file to GridFS with :class:`~motor.MotorGridIn`
from tornado import gen
import motor
- db = motor.MotorConnection().open_sync().test
+ db = motor.MotorClient().open_sync().test
@gen.engine
def write_file_streaming():
@@ -76,7 +76,7 @@ Setting attributes on a :class:`~motor.MotorGridIn`
from tornado import gen
import motor
- db = motor.MotorConnection().open_sync().test
+ db = motor.MotorClient().open_sync().test
@gen.engine
def set_attributes():
@@ -105,7 +105,7 @@ Reading from GridFS with :class:`~motor.MotorGridOut`
from tornado import gen
import motor
- db = motor.MotorConnection().open_sync().test
+ db = motor.MotorClient().open_sync().test
@gen.engine
def read_file(file_id):
@@ -9,7 +9,7 @@ Motor provides a convenience method :meth:`~motor.MotorCursor.tail`
from tornado import ioloop, gen
import motor
- db = motor.MotorConnection().open_sync().test
+ db = motor.MotorClient().open_sync().test
@gen.engine
def tailable_example():
View
@@ -40,18 +40,18 @@ timeout interface::
Configurable IOLoops
====================
Motor supports Tornado applications with multiple IOLoops_. Pass the ``io_loop``
-argument to :class:`~motor.MotorConnection`
-or :class:`~motor.MotorReplicaSetConnection` to configure the loop for a
-connection instance.
+argument to :class:`~motor.MotorClient`
+or :class:`~motor.MotorReplicaSetClient` to configure the loop for a
+client instance.
.. _IOLoops: http://www.tornadoweb.org/documentation/ioloop.html
Opens Connections Synchronously or Asynchronously
=================================================
-A :class:`~motor.MotorConnection` or :class:`~motor.MotorReplicaSetConnection`
-can be opened synchronously with :meth:`~motor.MotorConnection.open_sync`
+A :class:`~motor.MotorClient` or :class:`~motor.MotorReplicaSetClient`
+can be opened synchronously with :meth:`~motor.MotorClient.open_sync`
before your application begins serving request, or can be opened
-asynchronously with :meth:`~motor.MotorConnection.open` to make the connection
+asynchronously with :meth:`~motor.MotorClient.open` to make the connection
to MongoDB without blocking the Tornado IOLoop.
Streams Static Files from GridFS
View
@@ -21,8 +21,8 @@ Classes
.. toctree::
- motor_connection
- motor_replica_set_connection
+ motor_client
+ motor_replica_set_client
motor_database
motor_collection
motor_cursor
@@ -1,9 +1,9 @@
-:class:`MotorConnection` -- Connection to MongoDB
+:class:`MotorClient` -- Connection to MongoDB
=================================================
.. currentmodule:: motor
-.. autoclass:: motor.MotorConnection
+.. autoclass:: motor.MotorClient
.. automethod:: open
.. automethod:: open_sync
@@ -12,7 +12,7 @@
Disconnect from MongoDB.
Disconnecting will close all underlying sockets in the
- connection pool. If the :class:`MotorConnection` is used again it
+ connection pool. If the :class:`MotorClient` is used again it
will be automatically re-opened.
.. method:: close
@@ -21,7 +21,7 @@
.. describe:: c[db_name] || c.db_name
- Get the `db_name` :class:`MotorDatabase` on :class:`MotorConnection` `c`.
+ Get the `db_name` :class:`MotorDatabase` on :class:`MotorClient` `c`.
Raises :class:`~pymongo.errors.InvalidName` if an invalid database name is used.
Raises :class:`~pymongo.errors.InvalidOperation` if connection isn't opened yet.
@@ -39,10 +39,10 @@
.. automotorattribute:: slave_okay
.. automotorattribute:: safe
.. automotorattribute:: is_locked
- .. method:: sync_connection
+ .. method:: sync_client
- Get a :class:`~pymongo.connection.Connection` with the same
- configuration as this :class:`MotorConnection`
+ Get a :class:`~pymongo.mongo_client.MongoClient` with the same
+ configuration as this :class:`MotorClient`
.. automotormethod:: get_lasterror_options
.. automotormethod:: set_lasterror_options
@@ -1,9 +1,9 @@
-:class:`MotorReplicaSetConnection` -- Connection to MongoDB replica set
+:class:`MotorReplicaSetClient` -- Connection to MongoDB replica set
=======================================================================
.. currentmodule:: motor
-.. autoclass:: motor.MotorReplicaSetConnection
+.. autoclass:: motor.MotorReplicaSetClient
.. automethod:: open
.. automethod:: open_sync
@@ -12,7 +12,7 @@
Disconnect from MongoDB.
Disconnecting will close all underlying sockets in the
- connection pool. If the :class:`MotorReplicaSetConnection` is used again it
+ connection pool. If the :class:`MotorReplicaSetClient` is used again it
will be automatically re-opened.
.. method:: close
@@ -21,7 +21,7 @@
.. describe:: c[db_name] || c.db_name
- Get the `db_name` :class:`MotorDatabase` on :class:`MotorReplicaSetConnection` `c`.
+ Get the `db_name` :class:`MotorDatabase` on :class:`MotorReplicaSetClient` `c`.
Raises :class:`~pymongo.errors.InvalidName` if an invalid database name is used.
Raises :class:`~pymongo.errors.InvalidOperation` if connection isn't opened yet.
@@ -39,10 +39,10 @@
.. automotorattribute:: document_class
.. automotorattribute:: tz_aware
.. automotorattribute:: safe
- .. method:: sync_connection
+ .. method:: sync_client
- Get a :class:`~pymongo.replica_set_connection.ReplicaSetConnection`
- with the same configuration as this :class:`MotorReplicaSetConnection`
+ Get a :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`
+ with the same configuration as this :class:`MotorReplicaSetClient`
.. automotormethod:: get_lasterror_options
.. automotormethod:: set_lasterror_options
View
@@ -14,7 +14,7 @@ Motor Tutorial
import tornado.web
from tornado.ioloop import IOLoop
from tornado import gen
- db = motor.MotorConnection().open_sync().test_database
+ db = motor.MotorClient().open_sync().test_database
.. testsetup:: after-inserting-2000-docs
@@ -23,14 +23,14 @@ Motor Tutorial
import tornado.web
from tornado.ioloop import IOLoop
from tornado import gen
- db = motor.MotorConnection().open_sync().test_database
- pymongo.Connection().test_database.test_collection.insert(
+ db = motor.MotorClient().open_sync().test_database
+ pymongo.MongoClient().test_database.test_collection.insert(
[{'i': i} for i in range(2000)], safe=True)
.. testcleanup:: *
import pymongo
- pymongo.Connection().test_database.test_collection.remove(safe=True)
+ pymongo.MongoClient().test_database.test_collection.remove(safe=True)
A guide to using **MongoDB** and **Tornado** with **Motor**, the
non-blocking driver.
@@ -62,9 +62,9 @@ Object Hierarchy
----------------
Motor, like PyMongo, represents data with a 4-level object hierarchy:
-* :class:`~motor.MotorConnection` / :class:`~motor.MotorReplicaSetConnection`:
+* :class:`~motor.MotorClient` / :class:`~motor.MotorReplicaSetClient`:
represents a mongod process, or a cluster of them. You explicitly create one
- of these connection objects, connect it to a running mongod or mongods, and
+ of these client objects, connect it to a running mongod or mongods, and
use it for the lifetime of your application.
* :class:`~motor.MotorDatabase`: Each mongod has a set of databases (distinct
sets of data files on disk). You can get a reference to a database from a
@@ -77,24 +77,24 @@ Motor, like PyMongo, represents data with a 4-level object hierarchy:
Making a Connection
-------------------
-You typically create a single instance of either :class:`~motor.MotorConnection`
-or :class:`~motor.MotorReplicaSetConnection` at the time your application starts
+You typically create a single instance of either :class:`~motor.MotorClient`
+or :class:`~motor.MotorReplicaSetClient` at the time your application starts
up. (See :ref:`high-availability-and-pymongo` for an introduction to
MongoDB replica sets and how PyMongo connects to them.)
-You must call :meth:`~motor.MotorConnection.open_sync` on this connection object
+You must call :meth:`~motor.MotorClient.open_sync` on this connection object
before any other operations on it:
.. doctest:: before-inserting-2000-docs
- >>> connection = motor.MotorConnection().open_sync()
+ >>> connection = motor.MotorClient().open_sync()
This connects to a ``mongod`` listening on the default host and port. You can
specify the host and port like:
.. doctest:: before-inserting-2000-docs
- >>> connection = motor.MotorConnection('localhost', 27017).open_sync()
+ >>> connection = motor.MotorClient('localhost', 27017).open_sync()
Getting a Database
------------------
@@ -115,11 +115,11 @@ Tornado Application Startup Sequence
Now that we can open a connection and get a database, we're ready to start
a Tornado application that uses Motor.
-:meth:`~motor.MotorConnection.open_sync` is a blocking operation so it should
+:meth:`~motor.MotorClient.open_sync` is a blocking operation so it should
be called before listening for HTTP requests. Here's an example startup
sequence for a Tornado web application::
- db = motor.MotorConnection().open_sync().test_database
+ db = motor.MotorClient().open_sync().test_database
application = tornado.web.Application([
(r'/', MainHandler)
@@ -149,7 +149,7 @@ multiple subprocesses, you must create the connection object **after** calling
# start(0) starts a subprocess for each CPU core
server.start(0)
- db = motor.MotorConnection().open_sync().test_database
+ db = motor.MotorClient().open_sync().test_database
# Delayed initialization of settings
application.settings['db'] = db
@@ -568,8 +568,8 @@ the basic :meth:`command` method.
Further Reading
---------------
The handful of classes and methods introduced here are sufficient for daily
-tasks. The API documentation for :class:`~motor.MotorConnection`,
-:class:`~motor.MotorReplicaSetConnection`, :class:`~motor.MotorDatabase`,
+tasks. The API documentation for :class:`~motor.MotorClient`,
+:class:`~motor.MotorReplicaSetClient`, :class:`~motor.MotorDatabase`,
:class:`~motor.MotorCollection`, and :class:`~motor.MotorCursor` provides a
reference to Motor's complete feature set.
Oops, something went wrong.

0 comments on commit 3aa4948

Please sign in to comment.