Skip to content

Commit 4b47d47

Browse files
authored
PYTHON-2993 Deprecate MongoClient read only config option helpers and add client.options (#1095)
1 parent 5eb0236 commit 4b47d47

20 files changed

+165
-70
lines changed

doc/api/pymongo/client_options.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
:mod:`client_options` -- Read only configuration options for a MongoClient.
2+
===========================================================================
3+
4+
.. automodule:: pymongo.client_options
5+
6+
.. autoclass:: pymongo.client_options.ClientOptions()
7+
:members:

doc/api/pymongo/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ Sub-modules:
3333

3434
bulk
3535
change_stream
36+
client_options
3637
client_session
3738
collation
3839
collection

doc/api/pymongo/mongo_client.rst

+6-6
Original file line numberDiff line numberDiff line change
@@ -14,23 +14,17 @@
1414

1515
Raises :class:`~pymongo.errors.InvalidName` if an invalid database name is used.
1616

17-
.. autoattribute:: event_listeners
1817
.. autoattribute:: topology_description
1918
.. autoattribute:: address
2019
.. autoattribute:: primary
2120
.. autoattribute:: secondaries
2221
.. autoattribute:: arbiters
2322
.. autoattribute:: is_primary
2423
.. autoattribute:: is_mongos
25-
.. autoattribute:: max_pool_size
26-
.. autoattribute:: min_pool_size
27-
.. autoattribute:: max_idle_time_ms
2824
.. autoattribute:: nodes
2925
.. autoattribute:: max_bson_size
3026
.. autoattribute:: max_message_size
3127
.. autoattribute:: max_write_batch_size
32-
.. autoattribute:: local_threshold_ms
33-
.. autoattribute:: server_selection_timeout
3428
.. autoattribute:: codec_options
3529
.. autoattribute:: read_preference
3630
.. autoattribute:: write_concern
@@ -50,3 +44,9 @@
5044
.. autoattribute:: is_locked
5145
.. automethod:: fsync
5246
.. automethod:: unlock
47+
.. autoattribute:: event_listeners
48+
.. autoattribute:: max_pool_size
49+
.. autoattribute:: min_pool_size
50+
.. autoattribute:: max_idle_time_ms
51+
.. autoattribute:: local_threshold_ms
52+
.. autoattribute:: server_selection_timeout

doc/api/pymongo/pool.rst

+3-2
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,6 @@
22
==============================================================
33

44
.. automodule:: pymongo.pool
5-
:synopsis: Pool module for use with a MongoDB client.
6-
:members:
5+
6+
.. autoclass:: pymongo.pool.PoolOptions()
7+
:members:

doc/changelog.rst

+20-1
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,12 @@ Changelog
44
Changes in Version 3.13.0
55
-------------------------
66

7+
Notable improvements
8+
....................
9+
- Added :attr:`pymongo.mongo_client.MongoClient.options` for read-only access
10+
to a client's configuration options.
11+
12+
713
Issues Resolved
814
...............
915

@@ -19,10 +25,23 @@ Bug fixes
1925

2026
Deprecations
2127
............
22-
2328
- Deprecated :meth:`~pymongo.collection.Collection.map_reduce` and
2429
:meth:`~pymongo.collection.Collection.inline_map_reduce`.
2530
Use :meth:`~pymongo.collection.Collection.aggregate` instead.
31+
- Deprecated :attr:`pymongo.mongo_client.MongoClient.event_listeners`.
32+
Use :attr:`~pymongo.mongo_client.options.event_listeners` instead.
33+
- Deprecated :attr:`pymongo.mongo_client.MongoClient.max_pool_size`.
34+
Use :attr:`~pymongo.mongo_client.options.pool_options.max_pool_size` instead.
35+
- Deprecated :attr:`pymongo.mongo_client.MongoClient.max_idle_time_ms`.
36+
Use :attr:`~pymongo.mongo_client.options.pool_options.max_idle_time_seconds` instead.
37+
- Deprecated :attr:`pymongo.mongo_client.MongoClient.local_threshold_ms`.
38+
Use :attr:`~pymongo.mongo_client.options.local_threshold_ms` instead.
39+
- Deprecated :attr:`pymongo.mongo_client.MongoClient.server_selection_timeout`.
40+
Use :attr:`~pymongo.mongo_client.options.server_selection_timeout` instead.
41+
- Deprecated :attr:`pymongo.mongo_client.MongoClient.retry_writes`.
42+
Use :attr:`~pymongo.mongo_client.options.retry_writes` instead.
43+
- Deprecated :attr:`pymongo.mongo_client.MongoClient.retry_reads`.
44+
Use :attr:`~pymongo.mongo_client.options.retry_reads` instead.
2645

2746
See the `PyMongo 3.13.0 release notes in JIRA`_ for the list of resolved issues
2847
in this release.

pymongo/client_options.py

+14-3
Original file line numberDiff line numberDiff line change
@@ -149,8 +149,11 @@ def _parse_pool_options(options):
149149

150150

151151
class ClientOptions(object):
152-
153-
"""ClientOptions"""
152+
"""Read only configuration options for a MongoClient.
153+
Should not be instantiated directly by application developers. Access
154+
a client's options via :attr:`pymongo.mongo_client.MongoClient.options`
155+
instead.
156+
"""
154157

155158
def __init__(self, username, password, database, options):
156159
self.__options = options
@@ -193,7 +196,7 @@ def codec_options(self):
193196
return self.__codec_options
194197

195198
@property
196-
def credentials(self):
199+
def _credentials(self):
197200
"""A :class:`~pymongo.auth.MongoCredentials` instance or None."""
198201
return self.__credentials
199202

@@ -265,3 +268,11 @@ def auto_encryption_opts(self):
265268
def load_balanced(self):
266269
"""True if the client was configured to connect to a load balancer."""
267270
return self.__load_balanced
271+
272+
@property
273+
def event_listeners(self):
274+
"""The event listeners registered for this client.
275+
See :mod:`~pymongo.monitoring` for details.
276+
.. versionadded:: 4.0
277+
"""
278+
return self.__pool_options._event_listeners.event_listeners()

pymongo/encryption.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -269,7 +269,7 @@ def __init__(self, client, opts):
269269
self._internal_client = None
270270

271271
def _get_internal_client(encrypter, mongo_client):
272-
if mongo_client.max_pool_size is None:
272+
if mongo_client.options.pool_options.max_pool_size is None:
273273
# Unlimited pool size, use the same client.
274274
return mongo_client
275275
# Else - limited pool size, use an internal client.

pymongo/mongo_client.py

+58-12
Original file line numberDiff line numberDiff line change
@@ -735,7 +735,7 @@ def __init__(
735735
self.__cursor_manager = None
736736
self.__kill_cursors_queue = []
737737

738-
self._event_listeners = options.pool_options.event_listeners
738+
self._event_listeners = options.pool_options._event_listeners
739739

740740
# Cache of existing indexes used by ensure_index ops.
741741
self.__index_cache = {}
@@ -749,7 +749,7 @@ def __init__(
749749
)
750750

751751
self.__all_credentials = {}
752-
creds = options.credentials
752+
creds = options._credentials
753753
if creds:
754754
self._cache_credentials(creds.source, creds)
755755

@@ -1017,10 +1017,14 @@ def watch(
10171017

10181018
@property
10191019
def event_listeners(self):
1020-
"""The event listeners registered for this client.
1020+
"""**DEPRECATED**: The event listeners registered for this client.
10211021
10221022
See :mod:`~pymongo.monitoring` for details.
1023+
1024+
.. versionchanged:: 3.13
1025+
Deprecated. Use ``client.options.event_listeners`` instead.
10231026
"""
1027+
warnings.warn("event_listeners is deprecated. Use ``client.options.event_listeners`` instead.", DeprecationWarning, stacklevel=2)
10241028
return self._event_listeners.event_listeners
10251029

10261030
@property
@@ -1132,7 +1136,7 @@ def is_mongos(self):
11321136

11331137
@property
11341138
def max_pool_size(self):
1135-
"""The maximum allowable number of concurrent connections to each
1139+
"""**DEPRECATED**: The maximum allowable number of concurrent connections to each
11361140
connected server. Requests to a server will block if there are
11371141
`maxPoolSize` outstanding connections to the requested server.
11381142
Defaults to 100. Cannot be 0.
@@ -1142,22 +1146,33 @@ def max_pool_size(self):
11421146
``waitQueueTimeoutMS`` is set, a blocked operation will raise
11431147
:exc:`~pymongo.errors.ConnectionFailure` after a timeout.
11441148
By default ``waitQueueTimeoutMS`` is not set.
1149+
1150+
.. versionchanged:: 3.13
1151+
Deprecated. Use ``client.options.pool_options.max_pool_size`` instead.
11451152
"""
1153+
warnings.warn("max_pool_size is deprecated. Use ``client.options.pool_options.max_pool_size`` instead.", DeprecationWarning, stacklevel=2)
11461154
return self.__options.pool_options.max_pool_size
11471155

11481156
@property
11491157
def min_pool_size(self):
1150-
"""The minimum required number of concurrent connections that the pool
1158+
"""**DEPRECATED**: The minimum required number of concurrent connections that the pool
11511159
will maintain to each connected server. Default is 0.
1160+
.. versionchanged:: 3.13
1161+
Deprecated.
11521162
"""
1163+
warnings.warn("min_pool_size is deprecated. Use ``client.options.pool_options.min_pool_size`` instead.", DeprecationWarning, stacklevel=2)
11531164
return self.__options.pool_options.min_pool_size
11541165

11551166
@property
11561167
def max_idle_time_ms(self):
1157-
"""The maximum number of milliseconds that a connection can remain
1168+
"""**DEPRECATED**: The maximum number of milliseconds that a connection can remain
11581169
idle in the pool before being removed and replaced. Defaults to
11591170
`None` (no limit).
1171+
1172+
.. versionchanged:: 3.13
1173+
Deprecated. Use ``client.options.pool_options.max_idle_time_seconds`` instead.
11601174
"""
1175+
warnings.warn("max_idle_time_ms is deprecated. Use ``client.options.pool_options.max_idle_time_seconds`` instead.", DeprecationWarning, stacklevel=2)
11611176
seconds = self.__options.pool_options.max_idle_time_seconds
11621177
if seconds is None:
11631178
return None
@@ -1177,6 +1192,17 @@ def nodes(self):
11771192
description = self._topology.description
11781193
return frozenset(s.address for s in description.known_servers)
11791194

1195+
@property
1196+
def options(self):
1197+
"""The configuration options for this client.
1198+
1199+
:Returns:
1200+
An instance of :class:`~pymongo.client_options.ClientOptions`.
1201+
1202+
.. versionadded:: 3.13
1203+
"""
1204+
return self.__options
1205+
11801206
@property
11811207
def max_bson_size(self):
11821208
"""The largest BSON object the connected server accepts in bytes.
@@ -1212,22 +1238,42 @@ def max_write_batch_size(self):
12121238

12131239
@property
12141240
def local_threshold_ms(self):
1215-
"""The local threshold for this instance."""
1241+
"""**DEPRECATED**: The local threshold for this instance.
1242+
1243+
.. versionchanged:: 3.13
1244+
Deprecated. Use ``client.options.local_threshold_ms`` instead.
1245+
"""
1246+
warnings.warn("local_threshold_ms is deprecated. Use ``client.options.local_threshold_ms`` instead.", DeprecationWarning, stacklevel=2)
12161247
return self.__options.local_threshold_ms
12171248

12181249
@property
12191250
def server_selection_timeout(self):
1220-
"""The server selection timeout for this instance in seconds."""
1251+
"""**DEPRECATED**: The server selection timeout for this instance in seconds.
1252+
1253+
.. versionchanged:: 3.13
1254+
Deprecated. Use ``client.options.server_selection_timeout`` instead.
1255+
"""
1256+
warnings.warn("server_selection_timeout is deprecated. Use ``client.options.server_selection_timeout`` instead.", DeprecationWarning, stacklevel=2)
12211257
return self.__options.server_selection_timeout
12221258

12231259
@property
12241260
def retry_writes(self):
1225-
"""If this instance should retry supported write operations."""
1261+
"""**DEPRECATED**: If this instance should retry supported write operations.
1262+
1263+
.. versionchanged:: 3.13
1264+
Deprecated. Use ``client.options.retry_writes`` instead.
1265+
"""
1266+
warnings.warn("retry_writes is deprecated. Use ``client.options.retry_writes`` instead.", DeprecationWarning, stacklevel=2)
12261267
return self.__options.retry_writes
12271268

12281269
@property
12291270
def retry_reads(self):
1230-
"""If this instance should retry supported write operations."""
1271+
"""**DEPRECATED**: If this instance should retry supported write operations.
1272+
1273+
.. versionchanged:: 3.13
1274+
Deprecated. Use ``client.options.retry_reads`` instead.
1275+
"""
1276+
warnings.warn("retry_reads is deprecated. Use ``client.options.retry_reads`` instead.", DeprecationWarning, stacklevel=2)
12311277
return self.__options.retry_reads
12321278

12331279
def _is_writable(self):
@@ -1469,7 +1515,7 @@ def _retry_with_session(self, retryable, func, session, bulk):
14691515
14701516
Re-raises any exception thrown by func().
14711517
"""
1472-
retryable = retryable and self.retry_writes and session and not session.in_transaction
1518+
retryable = retryable and self.options.retry_writes and session and not session.in_transaction
14731519
return self._retry_internal(retryable, func, session, bulk)
14741520

14751521
def _retry_internal(self, retryable, func, session, bulk):
@@ -1538,7 +1584,7 @@ def _retryable_read(self, func, read_pref, session, address=None, retryable=True
15381584
15391585
Re-raises any exception thrown by func().
15401586
"""
1541-
retryable = retryable and self.retry_reads and not (session and session.in_transaction)
1587+
retryable = retryable and self.options.retry_reads and not (session and session.in_transaction)
15421588
last_error = None
15431589
retrying = False
15441590

pymongo/monitor.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ def __init__(self, server_description, topology, pool, topology_settings):
117117
self._server_description = server_description
118118
self._pool = pool
119119
self._settings = topology_settings
120-
self._listeners = self._settings._pool_options.event_listeners
120+
self._listeners = self._settings._pool_options._event_listeners
121121
pub = self._listeners is not None
122122
self._publish = pub and self._listeners.enabled_for_server_heartbeat
123123
self._cancel_context = None

pymongo/monitoring.py

+4-4
Original file line numberDiff line numberDiff line change
@@ -1381,10 +1381,10 @@ def enabled_for_cmap(self):
13811381
def event_listeners(self):
13821382
"""List of registered event listeners."""
13831383
return (
1384-
self.__command_listeners[:],
1385-
self.__server_heartbeat_listeners[:],
1386-
self.__server_listeners[:],
1387-
self.__topology_listeners[:],
1384+
self.__command_listeners +
1385+
self.__server_heartbeat_listeners +
1386+
self.__server_listeners +
1387+
self.__topology_listeners
13881388
)
13891389

13901390
def publish_command_start(

0 commit comments

Comments
 (0)