Merge branch 'master' into py3k

Conflicts:
	pymongo/connection.py
	pymongo/database.py
	pymongo/master_slave_connection.py
	test/test_database.py
	test/test_pooling.py
	test/test_thread_util.py
	tools/auto_reconnect_test.py

Author: sovnarkom

README.rst

@@ -6,19 +6,28 @@ PyMongo
 
 About
 =====
-The PyMongo distribution contains tools for interacting with the Mongo database from Python.
-The ``pymongo`` package is a native Python driver for the Mongo database. The ``gridfs``
-package is a `gridfs <http://www.mongodb.org/display/DOCS/GridFS+Specification>`_
+
+The PyMongo distribution contains tools for interacting with the Mongo
+database from Python.  The ``pymongo`` package is a native Python
+driver for the Mongo database. The ``gridfs`` package is a `gridfs
+<http://www.mongodb.org/display/DOCS/GridFS+Specification>`_
 implementation on top of ``pymongo``.
 
 Installation
 ============
-If you have `setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_ installed you should be able to do **easy_install pymongo** to install PyMongo. Otherwise you can download the project source and do **python setup.py install** to install.
+
+If you have `setuptools
+<http://peak.telecommunity.com/DevCenter/setuptools>`_ installed you
+should be able to do **easy_install pymongo** to install
+PyMongo. Otherwise you can download the project source and do **python
+setup.py install** to install.
 
 Dependencies
 ============
-The PyMongo distribution has been tested on Python 2.x, where x >= 3. On Python 2.3 the optional
-C extension will not be built. This will negatively affect performance, but everything should still work.
+
+The PyMongo distribution is supported and tested on Python 2.x, where
+x >= 4. PyMongo versions <= 1.3 also supported Python 2.3, but that is
+no longer supported. If you need to use Python 2.3 please contact us.
 
 Additional dependencies are:
 
@@ -63,10 +72,18 @@ u'x_1'
 
 Documentation
 =============
-You will need sphinx_ installed to generate the documentation. Documentation can be generated by running **python setup.py doc**. Generated documentation can be found in the *doc/build/html/* directory.
+
+You will need sphinx_ installed to generate the
+documentation. Documentation can be generated by running **python
+setup.py doc**. Generated documentation can be found in the
+*doc/build/html/* directory.
 
 Testing
 =======
-The easiest way to run the tests is to install `nose <http://somethingaboutorange.com/mrl/projects/nose/>`_ (**easy_install nose**) and run **nosetests** or **python setup.py test** in the root of the distribution. Tests are located in the *test/* directory.
+
+The easiest way to run the tests is to install `nose
+<http://somethingaboutorange.com/mrl/projects/nose/>`_ (**easy_install
+nose**) and run **nosetests** or **python setup.py test** in the root
+of the distribution. Tests are located in the *test/* directory.
 
 .. _sphinx: http://sphinx.pocoo.org/

doc/api/pymongo/connection.rst

@@ -4,9 +4,9 @@
 .. automodule:: pymongo.connection
    :synopsis: Tools for connecting to MongoDB
 
-   .. autoclass:: pymongo.connection.Connection([host='localhost'[, port=27017[, pool_size=1[, auto_start_request=True[, timeout=1.0[, slave_okay=False[, network_timeout=None]]]]]]])
+   .. autoclass:: pymongo.connection.Connection([host='localhost'[, port=27017[, pool_size=None[, auto_start_request=None[, timeout=None[, slave_okay=False[, network_timeout=None]]]]]]])
 
-      .. automethod:: paired(left[, right=('localhost', 27017)[, pool_size=1[, auto_start_request=True]]])
+      .. automethod:: paired(left[, right=('localhost', 27017)[, pool_size=None[, auto_start_request=None]]])
       .. automethod:: disconnect
 
       .. describe:: c[db_name] || c.db_name

doc/api/pymongo/index.rst

@@ -29,5 +29,4 @@ Sub-modules:
    son
    son_manipulator
    json_util
-   thread_util
    cursor_manager

doc/api/pymongo/thread_util.rst

@@ -5,19 +5,36 @@ Frequently Asked Questions
 
 Is PyMongo thread-safe?
 -----------------------
+
 PyMongo is thread-safe and even provides built-in connection pooling
-for threaded applications. See the documentation for
-:class:`~pymongo.connection.Connection`, notably the `pool_size`
-parameter.
+for threaded applications.
+
+How does connection pooling work in PyMongo?
+--------------------------------------------
+
+Every :class:`~pymongo.connection.Connection` instance has built-in
+connection pooling. Each thread gets its own socket reserved on its
+first operation. Those sockets are held until
+:meth:`~pymongo.connection.Connection.end_request` is called by that
+thread, or :meth:`~pymongo.connection.Connection.disconnect` is called
+by any thread, or the thread dies.
+
+Calling :meth:`~pymongo.connection.Connection.end_request` allows the
+socket to be returned to the pool, and to be used by other threads
+instead of creating a new socket. Judicious use of this method is
+important for applications with many threads or with long running
+threads that make few calls to PyMongo operations.
 
 How can I use PyMongo with an asynchronous socket library like `twisted <http://twistedmatrix.com/>`_?
 ------------------------------------------------------------------------------------------------------
+
 Currently there is no great way to use PyMongo in conjunction with
 asynchronous socket frameworks like `twisted
 <http://twistedmatrix.com/>`_ or `tornado
-<http://www.tornadoweb.org/>`_. One way to get the same benefits those
-frameworks provide using PyMongo is to write multi-threaded code and
-use PyMongo's built in connection pooling.
+<http://www.tornadoweb.org/>`_. PyMongo provides built-in connection
+pooling, so some of the benefits of those frameworks can be achieved
+just by writing multi-threaded code that shares a
+:class:`~pymongo.connection.Connection`.
 
 There is work in progress towards creating an `asynchronous Python
 driver <http://github.com/fiorix/mongo-async-python-driver>`_ for

doc/faq.rst

@@ -302,7 +302,6 @@ def remove(self, spec_or_object_id=None, safe=False):
            The `spec_or_object_id` parameter is now optional. If it is
            not specified *all* documents in the collection will be
            removed.
-
         .. versionadded:: 1.1
            The `safe` parameter.
         """
@@ -656,11 +655,11 @@ def group(self, key, condition, initial, reduce, finalize=None,
             command instead of in an eval - this option is deprecated and
             will be removed in favor of running all groups as commands
 
-        .. versionchanged:: 1.3
-           The `command` argument now defaults to ``True`` and is deprecated.
         .. versionchanged:: 1.3+
            The `key` argument can now be ``None`` or a JavaScript function,
            in addition to a :class:`list` of keys.
+        .. versionchanged:: 1.3
+           The `command` argument now defaults to ``True`` and is deprecated.
         """
         if not command:
             warnings.warn("eval-based groups are deprecated, and the "