PYTHON-2662 Deprecate database profiler helpers (#619)

(cherry picked from commit ac61cf8)

Author: prashantmital

doc/changelog.rst

@@ -32,10 +32,17 @@ Deprecations
 ............
 
 - Deprecated support for Python 2.7, 3.4 and 3.5.
+- Deprecated support for database profiler helpers
+  :meth:`~pymongo.database.Database.profiling_level`,
+  :meth:`~pymongo.database.Database.set_profiling_level`,
+  and :meth:`~pymongo.database.Database.profiling_info`. Instead, users
+  should run the `profile command`_ with the
+  :meth:`~pymongo.database.Database.command` helper directly.
 
 .. _PYTHON-2466: https://jira.mongodb.org/browse/PYTHON-2466
 .. _PYTHON-1690: https://jira.mongodb.org/browse/PYTHON-1690
 .. _PYTHON-2472: https://jira.mongodb.org/browse/PYTHON-2472
+.. _profile command: https://docs.mongodb.com/manual/reference/command/profile/
 
 Issues Resolved
 ...............

pymongo/__init__.py

@@ -68,11 +68,36 @@
 """
 
 OFF = 0
-"""No database profiling."""
+"""**DEPRECATED** - No database profiling.
+
+**DEPRECATED** - :attr:`OFF` is deprecated and will be removed in PyMongo 4.0.
+Instead, specify this profiling level using the numeric value ``0``.
+See https://docs.mongodb.com/manual/tutorial/manage-the-database-profiler
+
+.. versionchanged:: 3.12
+   Deprecated
+"""
 SLOW_ONLY = 1
-"""Only profile slow operations."""
+"""**DEPRECATED** - Only profile slow operations.
+
+**DEPRECATED** - :attr:`SLOW_ONLY` is deprecated and will be removed in
+PyMongo 4.0. Instead, specify this profiling level using the numeric
+value ``1``.
+See https://docs.mongodb.com/manual/tutorial/manage-the-database-profiler
+
+.. versionchanged:: 3.12
+   Deprecated
+"""
 ALL = 2
-"""Profile all operations."""
+"""**DEPRECATED** - Profile all operations.
+
+**DEPRECATED** - :attr:`ALL` is deprecated and will be removed in PyMongo 4.0.
+Instead, specify this profiling level using the numeric value ``2``.
+See https://docs.mongodb.com/manual/tutorial/manage-the-database-profiler
+
+.. versionchanged:: 3.12
+   Deprecated
+"""
 
 version_tuple = (3, 12, 0, 'b1.dev0')
 

pymongo/database.py

@@ -1067,7 +1067,18 @@ def current_op(self, include_all=False, session=None):
         return self._current_op(include_all, session)
 
     def profiling_level(self, session=None):
-        """Get the database's current profiling level.
+        """**DEPRECATED**: Get the database's current profiling level.
+
+        Starting with PyMongo 3.12, this helper is obsolete. Instead, users
+        can run the `profile command`_, using the :meth:`command`
+        helper to get the current profiler level. Running the
+        `profile command`_ with the level set to ``-1`` returns the current
+        profiler information without changing it::
+
+           res = db.command("profile", -1)
+           profiling_level = res["was"]
+
+        The format of ``res`` depends on the version of MongoDB in use.
 
         Returns one of (:data:`~pymongo.OFF`,
         :data:`~pymongo.SLOW_ONLY`, :data:`~pymongo.ALL`).
@@ -1076,19 +1087,32 @@ def profiling_level(self, session=None):
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession`.
 
+        .. versionchanged:: 3.12
+           Deprecated.
+
         .. versionchanged:: 3.6
            Added ``session`` parameter.
 
         .. mongodoc:: profiling
+        .. _profile command: https://docs.mongodb.com/manual/reference/command/profile/
         """
+        warnings.warn("profiling_level() is deprecated. See the documentation "
+                      "for more information",
+                      DeprecationWarning, stacklevel=2)
         result = self.command("profile", -1, session=session)
 
         assert result["was"] >= 0 and result["was"] <= 2
         return result["was"]
 
     def set_profiling_level(self, level, slow_ms=None, session=None,
                             sample_rate=None, filter=None):
-        """Set the database's profiling level.
+        """**DEPRECATED**: Set the database's profiling level.
+
+        Starting with PyMongo 3.12, this helper is obsolete. Instead, users
+        can directly run the `profile command`_, using the :meth:`command`
+        helper, e.g.::
+
+           res = db.command("profile", 2, filter={"op": "query"})
 
         :Parameters:
           - `level`: Specifies a profiling level, see list of possible values
@@ -1121,12 +1145,18 @@ def set_profiling_level(self, level, slow_ms=None, session=None,
 
         .. versionchanged:: 3.12
            Added the ``sample_rate`` and ``filter`` parameters.
+           Deprecated.
 
         .. versionchanged:: 3.6
            Added ``session`` parameter.
 
         .. mongodoc:: profiling
+        .. _profile command: https://docs.mongodb.com/manual/reference/command/profile/
         """
+        warnings.warn("set_profiling_level() is deprecated. See the "
+                      "documentation for more information",
+                      DeprecationWarning, stacklevel=2)
+
         if not isinstance(level, int) or level < 0 or level > 2:
             raise ValueError("level must be one of (OFF, SLOW_ONLY, ALL)")
 
@@ -1147,17 +1177,34 @@ def set_profiling_level(self, level, slow_ms=None, session=None,
         self.command(cmd, session=session)
 
     def profiling_info(self, session=None):
-        """Returns a list containing current profiling information.
+        """**DEPRECATED**: Returns a list containing current profiling
+        information.
+
+        Starting with PyMongo 3.12, this helper is obsolete. Instead, users
+        can view the database profiler output by running
+        :meth:`~pymongo.collection.Collection.find` against the
+        ``system.profile`` collection as detailed in the `profiler output`_
+        documentation::
+
+           profiling_info = list(db["system.profile"].find())
 
         :Parameters:
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession`.
 
+        .. versionchanged:: 3.12
+           Deprecated.
+
         .. versionchanged:: 3.6
            Added ``session`` parameter.
 
         .. mongodoc:: profiling
+        .. _profiler output: https://docs.mongodb.com/manual/reference/database-profiler/
         """
+        warnings.warn("profiling_info() is deprecated. See the "
+                      "documentation for more information",
+                      DeprecationWarning, stacklevel=2)
+
         return list(self["system.profile"].find(session=session))
 
     def error(self):

test/test_database.py

@@ -58,6 +58,7 @@
                         rs_or_single_client,
                         server_started_with_auth,
                         wait_until,
+                        DeprecationFilter,
                         IMPOSSIBLE_WRITE_CONCERN,
                         OvertCommandListener)
 from test.test_custom_types import DECIMAL_CODECOPTS
@@ -390,6 +391,7 @@ def test_validate_collection_background(self):
                 db.validate_collection(coll, full=True, background=True)
 
     @client_context.require_no_mongos
+    @ignore_deprecations
     def test_profiling_levels(self):
         db = self.client.pymongo_test
         self.assertEqual(db.profiling_level(), OFF)  # default
@@ -420,6 +422,7 @@ def test_profiling_levels(self):
 
     @client_context.require_no_mongos
     @client_context.require_version_min(3, 6)
+    @ignore_deprecations
     def test_profiling_sample_rate(self):
         db = self.client.pymongo_test
         with self.assertRaises(TypeError):
@@ -438,6 +441,7 @@ def test_profiling_sample_rate(self):
 
     @client_context.require_no_mongos
     @client_context.require_version_min(4, 4, 2)
+    @ignore_deprecations
     def test_profiling_filter(self):
         db = self.client.pymongo_test
         db.set_profiling_level(ALL, filter={'ns': {'$eq': 'test.test'}})
@@ -448,6 +452,7 @@ def test_profiling_filter(self):
         self.assertEqual(100, db.command("profile", -1)['slowms'])
 
     @client_context.require_no_mongos
+    @ignore_deprecations
     def test_profiling_info(self):
         db = self.client.pymongo_test
 
@@ -476,6 +481,14 @@ def test_profiling_info(self):
         self.assertTrue(isinstance(info[0]['op'], string_type))
         self.assertTrue(isinstance(info[0]["ts"], datetime.datetime))
 
+    def test_profiling_helpers_deprecated(self):
+        filter = DeprecationFilter('error')
+        self.addCleanup(filter.stop)
+        db = self.client.pymongo_test
+        self.assertRaises(DeprecationWarning, db.profiling_level)
+        self.assertRaises(DeprecationWarning, db.profiling_info)
+        self.assertRaises(DeprecationWarning, db.set_profiling_level, OFF)
+
     # SERVER-47817 removes the resetError command.
     @client_context.require_version_max(4, 9)
     @client_context.require_no_mongos