PYTHON-1310, PYTHON-1311 - Deprecate add_user and remove_user

Also document what to use instead.

Author: behackett

doc/changelog.rst

@@ -35,6 +35,9 @@ Deprecations:
 - The `useCursor` option for :meth:`~pymongo.collection.Collection.aggregate`
  is deprecated. The option was only necessary when upgrading from MongoDB
  2.4 to MongoDB 2.6. MongoDB 2.4 is no longer supported.
+- The :meth:`~pymongo.database.Database.add_user` and
+ :meth:`~pymongo.database.Database.remove_user` methods are deprecated. See
+ the method docstrings for alternatives.
 
 Breaking changes include:
 

pymongo/database.py

@@ -978,12 +978,38 @@ def _create_or_update_user(
 
  def add_user(self, name, password=None, read_only=None, session=None,
  **kwargs):
- """Create user `name` with password `password`.
+ """**DEPRECATED**: Create user `name` with password `password`.
 
  Add a new user with permissions for this :class:`Database`.
 
  .. note:: Will change the password if user `name` already exists.
 
+ .. note:: add_user is deprecated and will be removed in PyMongo
+ 4.0. Starting with MongoDB 2.6 user management is handled with four
+ database commands, createUser_, usersInfo_, updateUser_, and
+ dropUser_.
+
+ To create a user::
+
+ db.command("createUser", "admin", pwd="password", roles=["root"])
+
+ To create a read-only user::
+
+ db.command("createUser", "user", pwd="password", roles=["read"])
+
+ To change a password::
+
+ db.command("updateUser", "user", pwd="newpassword")
+
+ Or change roles::
+
+ db.command("updateUser", "user", roles=["readWrite"])
+
+ .. _createUser: https://docs.mongodb.com/manual/reference/command/createUser/
+ .. _usersInfo: https://docs.mongodb.com/manual/reference/command/usersInfo/
+ .. _updateUser: https://docs.mongodb.com/manual/reference/command/updateUser/
+ .. _dropUser: https://docs.mongodb.com/manual/reference/command/createUser/
+
  :Parameters:
  - `name`: the name of the user to create
  - `password` (optional): the password of the user to create. Can not
@@ -997,14 +1023,17 @@ def add_user(self, name, password=None, read_only=None, session=None,
  :class:`~pymongo.client_session.ClientSession`.
 
  .. versionchanged:: 3.6
- Added ``session`` parameter.
+ Added ``session`` parameter. Deprecated add_user.
 
  .. versionchanged:: 2.5
  Added kwargs support for optional fields introduced in MongoDB 2.4
 
  .. versionchanged:: 2.2
  Added support for read only users
  """
+ warnings.warn("add_user is deprecated and will be removed in PyMongo "
+ "4.0. Use db.command with createUser or updateUser "
+ "instead", DeprecationWarning, stacklevel=2)
  if not isinstance(name, string_type):
  raise TypeError("name must be an "
  "instance of %s" % (string_type.__name__,))
@@ -1036,19 +1065,27 @@ def add_user(self, name, password=None, read_only=None, session=None,
  raise
 
  def remove_user(self, name, session=None):
- """Remove user `name` from this :class:`Database`.
+ """**DEPRECATED**: Remove user `name` from this :class:`Database`.
 
  User `name` will no longer have permissions to access this
  :class:`Database`.
 
+ .. note:: remove_user is deprecated and will be removed in PyMongo
+ 4.0. Use the dropUser command instead::
+
+ db.command("dropUser", "user")
+
  :Parameters:
  - `name`: the name of the user to remove
  - `session` (optional): a
  :class:`~pymongo.client_session.ClientSession`.
 
  .. versionchanged:: 3.6
- Added ``session`` parameter.
+ Added ``session`` parameter. Deprecated remove_user.
  """
+ warnings.warn("remove_user is deprecated and will be removed in "
+ "PyMongo 4.0. Use db.command with dropUser "
+ "instead", DeprecationWarning, stacklevel=2)
  cmd = SON([("dropUser", name)])
  # Don't send {} as writeConcern.
  if self.write_concern.acknowledged and self.write_concern.document: