PYTHON-3984 Deprecate WriteConcern.wtimeout in favor of pymongo.timeout() (#1591)

Author: blink1073

doc/changelog.rst

@@ -43,7 +43,8 @@ PyMongo 4.7 brings a number of improvements including:
   creating vector search indexes in MongoDB Atlas.
 - Fixed a bug where ``read_concern`` and ``write_concern`` were improperly added to
   :meth:`~pymongo.collection.Collection.list_search_indexes` queries.
-
+- Deprecated :attr:`pymongo.write_concern.WriteConcern.wtimeout` and :attr:`pymongo.mongo_client.MongoClient.wTimeoutMS`.
+  Use :meth:`~pymongo.timeout` instead.
 
 Unavoidable breaking changes
 ............................

pymongo/mongo_client.py

@@ -439,8 +439,8 @@ def __init__(
             primary (e.g. w=3 means write to the primary and wait until
             replicated to **two** secondaries). Passing w=0 **disables write
             acknowledgement** and all other write concern options.
-          - `wTimeoutMS`: (integer) Used in conjunction with `w`. Specify a value
-            in milliseconds to control how long to wait for write propagation
+          - `wTimeoutMS`: **DEPRECATED** (integer) Used in conjunction with `w`.
+            Specify a value in milliseconds to control how long to wait for write propagation
             to complete. If replication does not complete in the given
             timeframe, a timeout exception is raised. Passing wTimeoutMS=0
             will cause **write operations to wait indefinitely**.
@@ -717,6 +717,9 @@ def __init__(
            Not::
 
                client.__my_database__
+
+        .. versionchanged:: 4.7
+            Deprecated parameter ``wTimeoutMS``, use :meth:`~pymongo.timeout`.
         """
         doc_class = document_class or dict
         self.__init_kwargs: dict[str, Any] = {

pymongo/write_concern.py

@@ -38,9 +38,9 @@ class WriteConcern:
           replicated to **two** secondaries). **w=0 disables acknowledgement
           of write operations and can not be used with other write concern
           options.**
-    :param wtimeout: (integer) Used in conjunction with `w`. Specify a value
-          in milliseconds to control how long to wait for write propagation
-          to complete. If replication does not complete in the given
+    :param wtimeout: (integer) **DEPRECATED** Used in conjunction with `w`.
+          Specify a value in milliseconds to control how long to wait for write
+          propagation to complete. If replication does not complete in the given
           timeframe, a timeout exception is raised.
     :param j: If ``True`` block until write operations have been committed
           to the journal. Cannot be used in combination with `fsync`. Write
@@ -51,6 +51,10 @@ class WriteConcern:
           server is running with journaling, this acts the same as the `j`
           option, blocking until write operations have been committed to the
           journal. Cannot be used in combination with `j`.
+
+
+    .. versionchanged:: 4.7
+        Deprecated parameter ``wtimeout``, use :meth:`~pymongo.timeout`.
     """
 
     __slots__ = ("__document", "__acknowledged", "__server_default")