PYTHON-783 Deprecate copy_database.

doc/examples/copydb.rst

@@ -38,7 +38,12 @@ See the :doc:`authentication examples </examples/authentication>`.
 
 The current version of PyMongo provides a helper method,
 :meth:`~pymongo.mongo_client.MongoClient.copy_database`, to copy a database
-from a password-protected mongod server to the target server::
+from a password-protected mongod server to the target server.
+This method is deprecated and will be removed in PyMongo 3.0.
+Use the `copyDatabase function in the mongo shell`_ instead.
+
+Until the method is removed from PyMongo, you can copy a database from a
+password-protected server like so::
 
   >>> client = MongoClient('target.example.com')
   >>> client.copy_database(from_name='source_db_name',
@@ -61,3 +66,6 @@ connected to a pre-2.8 version of MongoDB, and SCRAM-SHA-1 when connected to
 a recent version. However, since PyMongo cannot determine the MongoDB
 version of the **source** host, it is better if you specify a mechanism
 yourself.
+
+.. _copyDatabase function in the mongo shell:
+   http://docs.mongodb.org/manual/reference/method/db.copyDatabase/

pymongo/helpers.py

@@ -16,6 +16,7 @@
 
 import random
 import struct
+import warnings
 
 import bson
 import pymongo
@@ -267,6 +268,11 @@ def _copy_database(
 
     _check_database_name(todb)
 
+    warnings.warn("copy_database is deprecated. Use the raw 'copydb' command"
+                  " or db.copyDatabase() in the mongo shell. See"
+                  " doc/examples/copydb.",
+                  DeprecationWarning, stacklevel=2)
+
     # It would be better if the user told us what mechanism to use, but for
     # backwards compatibility with earlier PyMongos we don't require the
     # mechanism. Hope 'fromhost' runs the same version as the target.

pymongo/mongo_client.py

@@ -1400,7 +1400,10 @@ class MongoClient(common.BaseObject):
     def copy_database(self, from_name, to_name,
                       from_host=None, username=None, password=None,
                       mechanism='DEFAULT'):
-        """Copy a database, potentially from another host.
+        """**DEPRECATED**: Copy a database, potentially from another host.
+
+        :meth:`copy_database` will be removed in PyMongo 3.0. See the
+        :doc:`copy_database examples </examples/copydb>` for alternatives.
 
         Raises :class:`TypeError` if `from_name` or `to_name` is not
         an instance of :class:`basestring` (:class:`str` in python 3).
@@ -1423,10 +1426,8 @@ class MongoClient(common.BaseObject):
           - `password` (optional): password for source database
           - `mechanism` (optional): auth method, 'MONGODB-CR' or 'SCRAM-SHA-1'
 
-        .. seealso:: The :doc:`copy_database examples </examples/copydb>`.
-
         .. versionadded:: 2.8
-           SCRAM-SHA-1 support.
+           Deprecated copy_database, and added SCRAM-SHA-1 support.
         """
         member = self.__ensure_member()
         sock_info = self.__socket(member)

pymongo/mongo_replica_set_client.py

@@ -1887,7 +1887,10 @@ class MongoReplicaSetClient(common.BaseObject):
     def copy_database(self, from_name, to_name,
                       from_host=None, username=None, password=None,
                       mechanism='DEFAULT'):
-        """Copy a database, potentially from another host.
+        """**DEPRECATED**: Copy a database, potentially from another host.
+
+        :meth:`copy_database` will be removed in PyMongo 3.0. See the
+        :doc:`copy_database examples </examples/copydb>` for alternatives.
 
         Raises :class:`TypeError` if `from_name` or `to_name` is not
         an instance of :class:`basestring` (:class:`str` in python 3).
@@ -1913,7 +1916,7 @@ class MongoReplicaSetClient(common.BaseObject):
         .. seealso:: The :doc:`copy_database examples </examples/copydb>`.
 
         .. versionadded:: 2.8
-           SCRAM-SHA-1 support.
+           Deprecated copy_database, and added SCRAM-SHA-1 support.
         """
         member = self.__find_primary()
         sock_info = self.__socket(member)