PYTHON-1839 Deprecate waitQueueMultiple option

Author: prashantmital

doc/changelog.rst

@@ -32,6 +32,9 @@ Version 3.9 adds support for MongoDB 4.2. Highlights include:
  - ``ssl_ca_certs`` has been deprecated in favor of ``tlsCAFile``.
  - ``ssl_certfile`` has been deprecated in favor of ``tlsCertificateKeyFile``.
  - ``ssl_pem_passphrase`` has been deprecated in favor of ``tlsCertificateKeyFilePassword``.
+ - ``waitQueueMultiple`` has been deprecated without replacement. This option
+ was a poor solution for putting an upper bound on queuing since it didn't
+ affect queuing in other parts of the driver.
 - The ``retryWrites`` URI option now defaults to ``True``. Supported write
  operations that fail with a retryable error will automatically be retried one
  time, with at-most-once semantics.

doc/faq.rst

@@ -98,21 +98,12 @@ process, increase ``maxPoolSize``::
 
  client = MongoClient(host, port, maxPoolSize=None)
 
-By default, any number of threads are allowed to wait for sockets to become
-available, and they can wait any length of time. Override ``waitQueueMultiple``
-to cap the number of waiting threads. E.g., to keep the number of waiters less
-than or equal to 500::
-
- client = MongoClient(host, port, maxPoolSize=50, waitQueueMultiple=10)
-
-When 500 threads are waiting for a socket, the 501st that needs a socket
-raises :exc:`~pymongo.errors.ExceededMaxWaiters`. Use this option to
-bound the amount of queueing in your application during a load spike, at the
-cost of additional exceptions.
-
-Once the pool reaches its max size, additional threads are allowed to wait
-indefinitely for sockets to become available, unless you set
-``waitQueueTimeoutMS``::
+Once the pool reaches its maximum size, additional threads have to wait for
+sockets to become available. PyMongo does not limit the number of threads
+that can wait for sockets to become available and it is the application's
+responsibility to limit the size of its thread pool to bound queuing during a
+load spike. Threads are allowed to wait for any length of time unless
+``waitQueueTimeoutMS`` is defined::
 
  client = MongoClient(host, port, waitQueueTimeoutMS=100)
 

pymongo/common.py

@@ -658,16 +658,26 @@ def validate_tzinfo(dummy, value):
  'tlscertificatekeyfilepassword': 'ssl_pem_passphrase',
 }
 
-# Map from deprecated URI option names to the updated option names.
-# Case is preserved for updated option names as they are part of user warnings.
+# Map from deprecated URI option names to a tuple indicating the method of
+# their deprecation and any additional information that may be needed to
+# construct the warning message.
 URI_OPTIONS_DEPRECATION_MAP = {
- 'j': 'journal',
- 'wtimeout': 'wTimeoutMS',
- 'ssl_cert_reqs': 'tlsAllowInvalidCertificates',
- 'ssl_match_hostname': 'tlsAllowInvalidHostnames',
- 'ssl_crlfile': 'tlsCRLFile',
- 'ssl_ca_certs': 'tlsCAFile',
- 'ssl_pem_passphrase': 'tlsCertificateKeyFilePassword',
+ # format: <deprecated option name>: (<mode>, <message>),
+ # Supported <mode> values:
+ # - 'renamed': <message> should be the new option name. Note that case is
+ # preserved for renamed options as they are part of user warnings.
+ # - 'removed': <message> may suggest the rationale for deprecating the
+ # option and/or recommend remedial action.
+ 'j': ('renamed', 'journal'),
+ 'wtimeout': ('renamed', 'wTimeoutMS'),
+ 'ssl_cert_reqs': ('renamed', 'tlsAllowInvalidCertificates'),
+ 'ssl_match_hostname': ('renamed', 'tlsAllowInvalidHostnames'),
+ 'ssl_crlfile': ('renamed', 'tlsCRLFile'),
+ 'ssl_ca_certs': ('renamed', 'tlsCAFile'),
+ 'ssl_pem_passphrase': ('renamed', 'tlsCertificateKeyFilePassword'),
+ 'waitqueuemultiple': ('removed', (
+ 'Instead of using waitQueueMultiple to bound queuing, limit the size '
+ 'of the thread pool in your application server'))
 }
 
 # Augment the option validator map with pymongo-specific option information.

pymongo/uri_parser.py

@@ -195,16 +195,27 @@ def _handle_option_deprecations(options):
  """
  for optname in list(options):
  if optname in URI_OPTIONS_DEPRECATION_MAP:
- newoptname = URI_OPTIONS_DEPRECATION_MAP[optname]
- if newoptname in options:
- warn_msg = "Deprecated option '%s' ignored in favor of '%s'."
- warnings.warn(warn_msg % (options.cased_key(optname),
- options.cased_key(newoptname)))
- options.pop(optname)
- continue
- warn_msg = "Option '%s' is deprecated, use '%s' instead."
- warnings.warn(warn_msg % (options.cased_key(optname),
- newoptname))
+ mode, message = URI_OPTIONS_DEPRECATION_MAP[optname]
+ if mode == 'renamed':
+ newoptname = message
+ if newoptname in options:
+ warn_msg = ("Deprecated option '%s' ignored in favor of "
+ "'%s'.")
+ warnings.warn(
+ warn_msg % (options.cased_key(optname),
+ options.cased_key(newoptname)),
+ DeprecationWarning, stacklevel=2)
+ options.pop(optname)
+ continue
+ warn_msg = "Option '%s' is deprecated, use '%s' instead."
+ warnings.warn(
+ warn_msg % (options.cased_key(optname), newoptname),
+ DeprecationWarning, stacklevel=2)
+ elif mode == 'removed':
+ warn_msg = "Option '%s' is deprecated. %s."
+ warnings.warn(
+ warn_msg % (options.cased_key(optname), message),
+ DeprecationWarning, stacklevel=2)
 
  return options
 

test/test_uri_parser.py

@@ -485,6 +485,15 @@ def test_normalize_options(self):
  "fsync": True, "wtimeoutms": 10}
  self.assertEqual(res, parse_uri(uri)["options"])
 
+ def test_waitQueueMultiple_deprecated(self):
+ uri = "mongodb://example.com/?waitQueueMultiple=5"
+ with warnings.catch_warnings(record=True) as ctx:
+ warnings.simplefilter('always')
+ parse_uri(uri)
+
+ self.assertEqual(len(ctx), 1)
+ self.assertTrue(issubclass(ctx[0].category, DeprecationWarning))
+
 
 if __name__ == "__main__":
  unittest.main()