1Changelog 2========= 3 4Changes in Version 3.12.0 5------------------------- 6 7.. warning:: PyMongo 3.12.0 deprecates support for Python 2.7, 3.4 and 3.5. 8 These Python versions will not be supported by PyMongo 4. 9 10.. warning:: PyMongo now allows insertion of documents with keys that include 11 dots ('.') or start with dollar signs ('$'). 12 13- PyMongoCrypt 1.1.0 or later is now required for client side field level 14 encryption support. 15 16Notable improvements 17.................... 18 19- Added support for MongoDB 5.0. 20- Support for MongoDB Versioned API, see :class:`~pymongo.server_api.ServerApi`. 21- Support for snapshot reads on secondaries (see :ref:`snapshot-reads-ref`). 22- Support for Azure and GCP KMS providers for client side field level 23 encryption. See the docstring for :class:`~pymongo.mongo_client.MongoClient`, 24 :class:`~pymongo.encryption_options.AutoEncryptionOpts`, 25 and :mod:`~pymongo.encryption`. 26- Support AWS authentication with temporary credentials when connecting to KMS 27 in client side field level encryption. 28- Support for connecting to load balanced MongoDB clusters via the new 29 ``loadBalanced`` URI option. 30- Support for creating timeseries collections via the ``timeseries`` and 31 ``expireAfterSeconds`` arguments to 32 :meth:`~pymongo.database.Database.create_collection`. 33- Added :attr:`pymongo.mongo_client.MongoClient.topology_description`. 34- Added hash support to :class:`~pymongo.mongo_client.MongoClient`, 35 :class:`~pymongo.database.Database` and 36 :class:`~pymongo.collection.Collection` (`PYTHON-2466`_). 37- Improved the error message returned by 38 :meth:`~pymongo.collection.Collection.insert_many` when supplied with an 39 argument of incorrect type (`PYTHON-1690`_). 40- Added session and read concern support to 41 :meth:`~pymongo.collection.Collection.find_raw_batches` 42 and :meth:`~pymongo.collection.Collection.aggregate_raw_batches`. 43 44Bug fixes 45......... 46 47- Fixed a bug that could cause the driver to deadlock during automatic 48 client side field level encryption (`PYTHON-2472`_). 49- Fixed a potential deadlock when garbage collecting an unclosed exhaust 50 :class:`~pymongo.cursor.Cursor`. 51- Fixed an bug where using gevent.Timeout to timeout an operation could 52 lead to a deadlock. 53- Fixed the following bug with Atlas Data Lake. When closing cursors, 54 pymongo now sends killCursors with the namespace returned the cursor's 55 initial command response. 56- Fixed a bug in :class:`~pymongo.cursor.RawBatchCursor` that caused it to 57 return an empty bytestring when the cursor contained no results. It now 58 raises :exc:`StopIteration` instead. 59 60Deprecations 61............ 62 63- Deprecated support for Python 2.7, 3.4 and 3.5. 64- Deprecated support for database profiler helpers 65 :meth:`~pymongo.database.Database.profiling_level`, 66 :meth:`~pymongo.database.Database.set_profiling_level`, 67 and :meth:`~pymongo.database.Database.profiling_info`. Instead, users 68 should run the `profile command`_ with the 69 :meth:`~pymongo.database.Database.command` helper directly. 70- Deprecated :exc:`~pymongo.errors.NotMasterError`. Users should 71 use :exc:`~pymongo.errors.NotPrimaryError` instead. 72- Deprecated :class:`~pymongo.ismaster.IsMaster` and :mod:`~pymongo.ismaster` 73 which will be removed in PyMongo 4.0 and are replaced by 74 :class:`~pymongo.hello.Hello` and :mod:`~pymongo.hello` which provide the 75 same API. 76- Deprecated the :mod:`pymongo.messeage` module. 77- Deprecated the ``ssl_keyfile`` and ``ssl_certfile`` URI options in favor 78 of ``tlsCertificateKeyFile`` (see :doc:`examples/tls`). 79 80.. _PYTHON-2466: https://jira.mongodb.org/browse/PYTHON-2466 81.. _PYTHON-1690: https://jira.mongodb.org/browse/PYTHON-1690 82.. _PYTHON-2472: https://jira.mongodb.org/browse/PYTHON-2472 83.. _profile command: https://docs.mongodb.com/manual/reference/command/profile/ 84 85Issues Resolved 86............... 87 88See the `PyMongo 3.12.0 release notes in JIRA`_ for the list of resolved issues 89in this release. 90 91.. _PyMongo 3.12.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=29594 92 93 94Changes in Version 3.11.3 95------------------------- 96 97Issues Resolved 98............... 99 100Version 3.11.3 fixes a bug that prevented PyMongo from retrying writes after 101a ``writeConcernError`` on MongoDB 4.4+ (`PYTHON-2452`_) 102 103See the `PyMongo 3.11.3 release notes in JIRA`_ for the list of resolved issues 104in this release. 105 106.. _PYTHON-2452: https://jira.mongodb.org/browse/PYTHON-2452 107.. _PyMongo 3.11.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=30355 108 109Changes in Version 3.11.2 110------------------------- 111 112Issues Resolved 113............... 114 115Version 3.11.2 includes a number of bugfixes. Highlights include: 116 117- Fixed a memory leak caused by failing SDAM monitor checks on Python 3 (`PYTHON-2433`_). 118- Fixed a regression that changed the string representation of 119 :exc:`~pymongo.errors.BulkWriteError` (`PYTHON-2438`_). 120- Fixed a bug that made it impossible to use 121 :meth:`bson.codec_options.CodecOptions.with_options` and 122 :meth:`~bson.json_util.JSONOptions.with_options` on some early versions of 123 Python 3.4 and Python 3.5 due to a bug in the standard library implementation 124 of :meth:`collections.namedtuple._asdict` (`PYTHON-2440`_). 125- Fixed a bug that resulted in a :exc:`TypeError` exception when a PyOpenSSL 126 socket was configured with a timeout of ``None`` (`PYTHON-2443`_). 127 128See the `PyMongo 3.11.2 release notes in JIRA`_ for the list of resolved issues 129in this release. 130 131.. _PYTHON-2433: https://jira.mongodb.org/browse/PYTHON-2433 132.. _PYTHON-2438: https://jira.mongodb.org/browse/PYTHON-2438 133.. _PYTHON-2440: https://jira.mongodb.org/browse/PYTHON-2440 134.. _PYTHON-2443: https://jira.mongodb.org/browse/PYTHON-2443 135.. _PyMongo 3.11.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=30315 136 137Changes in Version 3.11.1 138------------------------- 139 140Version 3.11.1 adds support for Python 3.9 and includes a number of bugfixes. 141Highlights include: 142 143- Support for Python 3.9. 144- Initial support for Azure and GCP KMS providers for client side field level 145 encryption is in beta. See the docstring for 146 :class:`~pymongo.mongo_client.MongoClient`, 147 :class:`~pymongo.encryption_options.AutoEncryptionOpts`, 148 and :mod:`~pymongo.encryption`. **Note: Backwards-breaking changes may be 149 made before the final release.** 150- Fixed a bug where the :class:`bson.json_util.JSONOptions` API did not match 151 the :class:`bson.codec_options.CodecOptions` API due to the absence of 152 a :meth:`bson.json_util.JSONOptions.with_options` method. This method has now 153 been added. 154- Fixed a bug which made it impossible to serialize 155 :class:`~pymongo.errors.BulkWriteError` instances using :mod:`pickle`. 156- Fixed a bug wherein PyMongo did not always discard an implicit session after 157 encountering a network error. 158- Fixed a bug where connections created in the background were not 159 authenticated. 160- Fixed a memory leak in the :mod:`bson` module when using a 161 :class:`~bson.codec_options.TypeRegistry`. 162 163Issues Resolved 164............... 165 166See the `PyMongo 3.11.1 release notes in JIRA`_ for the list of resolved issues 167in this release. 168 169.. _PyMongo 3.11.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=29997 170 171 172Changes in Version 3.11.0 173------------------------- 174 175Version 3.11 adds support for MongoDB 4.4 and includes a number of bug fixes. 176Highlights include: 177 178- Support for :ref:`OCSP` (Online Certificate Status Protocol). 179- Support for `PyOpenSSL <https://pypi.org/project/pyOpenSSL/>`_ as an 180 alternative TLS implementation. PyOpenSSL is required for :ref:`OCSP` 181 support. It will also be installed when using the "tls" extra if the 182 version of Python in use is older than 2.7.9. 183- Support for the :ref:`MONGODB-AWS` authentication mechanism. 184- Support for the ``directConnection`` URI option and kwarg to 185 :class:`~pymongo.mongo_client.MongoClient`. 186- Support for speculative authentication attempts in connection handshakes 187 which reduces the number of network roundtrips needed to authenticate new 188 connections on MongoDB 4.4+. 189- Support for creating collections in multi-document transactions with 190 :meth:`~pymongo.database.Database.create_collection` on MongoDB 4.4+. 191- Added index hinting support to the 192 :meth:`~pymongo.collection.Collection.replace_one`, 193 :meth:`~pymongo.collection.Collection.update_one`, 194 :meth:`~pymongo.collection.Collection.update_many`, 195 :meth:`~pymongo.collection.Collection.find_one_and_replace`, 196 :meth:`~pymongo.collection.Collection.find_one_and_update`, 197 :meth:`~pymongo.collection.Collection.delete_one`, 198 :meth:`~pymongo.collection.Collection.delete_many`, and 199 :meth:`~pymongo.collection.Collection.find_one_and_delete` commands. 200- Added index hinting support to the 201 :class:`~pymongo.operations.ReplaceOne`, 202 :class:`~pymongo.operations.UpdateOne`, 203 :class:`~pymongo.operations.UpdateMany`, 204 :class:`~pymongo.operations.DeleteOne`, and 205 :class:`~pymongo.operations.DeleteMany` bulk operations. 206- Added support for :data:`bson.binary.UuidRepresentation.UNSPECIFIED` and 207 ``MongoClient(uuidRepresentation='unspecified')`` which will become the 208 default UUID representation starting in PyMongo 4.0. See 209 :ref:`handling-uuid-data-example` for details. 210- Added the ``background`` parameter to 211 :meth:`pymongo.database.Database.validate_collection`. For a description 212 of this parameter see the MongoDB documentation for the `validate command`_. 213- Added the ``allow_disk_use`` parameters to 214 :meth:`pymongo.collection.Collection.find`. 215- Added the ``hedge`` parameter to 216 :class:`~pymongo.read_preferences.PrimaryPreferred`, 217 :class:`~pymongo.read_preferences.Secondary`, 218 :class:`~pymongo.read_preferences.SecondaryPreferred`, 219 :class:`~pymongo.read_preferences.Nearest` to support disabling 220 (or explicitly enabling) hedged reads in MongoDB 4.4+. 221- Fixed a bug in change streams that could cause PyMongo to miss some change 222 documents when resuming a stream that was started without a resume token and 223 whose first batch did not contain any change documents. 224- Fixed an bug where using gevent.Timeout to timeout an operation could 225 lead to a deadlock. 226 227Deprecations: 228 229- Deprecated the ``oplog_replay`` parameter to 230 :meth:`pymongo.collection.Collection.find`. Starting in MongoDB 4.4, the 231 server optimizes queries against the oplog collection without requiring 232 the user to set this flag. 233- Deprecated :meth:`pymongo.collection.Collection.reindex`. Use 234 :meth:`~pymongo.database.Database.command` to run the ``reIndex`` command 235 instead. 236- Deprecated :meth:`pymongo.mongo_client.MongoClient.fsync`. Use 237 :meth:`~pymongo.database.Database.command` to run the ``fsync`` command 238 instead. 239- Deprecated :meth:`pymongo.mongo_client.MongoClient.unlock`. Use 240 :meth:`~pymongo.database.Database.command` to run the ``fsyncUnlock`` command 241 instead. See the documentation for more information. 242- Deprecated :attr:`pymongo.mongo_client.MongoClient.is_locked`. Use 243 :meth:`~pymongo.database.Database.command` to run the ``currentOp`` command 244 instead. See the documentation for more information. 245 246Unavoidable breaking changes: 247 248- :class:`~gridfs.GridFSBucket` and :class:`~gridfs.GridFS` do not support 249 multi-document transactions. Running a GridFS operation in a transaction 250 now always raises the following error: 251 ``InvalidOperation: GridFS does not support multi-document transactions`` 252 253.. _validate command: https://docs.mongodb.com/manual/reference/command/validate/ 254 255Issues Resolved 256............... 257 258See the `PyMongo 3.11.0 release notes in JIRA`_ for the list of resolved issues 259in this release. 260 261.. _PyMongo 3.11.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=24799 262 263Changes in Version 3.10.1 264------------------------- 265 266Version 3.10.1 fixes the following issues discovered since the release of 2673.10.0: 268 269- Fix a TypeError logged to stderr that could be triggered during server 270 maintenance or during :meth:`pymongo.mongo_client.MongoClient.close`. 271- Avoid creating new connections during 272 :meth:`pymongo.mongo_client.MongoClient.close`. 273 274Issues Resolved 275............... 276 277See the `PyMongo 3.10.1 release notes in JIRA`_ for the list of resolved issues 278in this release. 279 280.. _PyMongo 3.10.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=25039 281 282Changes in Version 3.10.0 283------------------------- 284 285Version 3.10 includes a number of improvements and bug fixes. Highlights 286include: 287 288- Support for Client-Side Field Level Encryption with MongoDB 4.2. See 289 :doc:`examples/encryption` for examples. 290- Support for Python 3.8. 291- Added :attr:`pymongo.client_session.ClientSession.in_transaction`. 292- Do not hold the Topology lock while creating connections in a MongoClient's 293 background thread. This change fixes a bug where application operations would 294 block while the background thread ensures that all server pools have 295 minPoolSize connections. 296- Fix a UnicodeDecodeError bug when coercing a PyMongoError with a non-ascii 297 error message to unicode on Python 2. 298- Fix an edge case bug where PyMongo could exceed the server's 299 maxMessageSizeBytes when generating a compressed bulk write command. 300 301Issues Resolved 302............... 303 304See the `PyMongo 3.10 release notes in JIRA`_ for the list of resolved issues 305in this release. 306 307.. _PyMongo 3.10 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=23944 308 309Changes in Version 3.9.0 310------------------------ 311 312Version 3.9 adds support for MongoDB 4.2. Highlights include: 313 314- Support for MongoDB 4.2 sharded transactions. Sharded transactions have 315 the same API as replica set transactions. See :ref:`transactions-ref`. 316- New method :meth:`pymongo.client_session.ClientSession.with_transaction` to 317 support conveniently running a transaction in a session with automatic 318 retries and at-most-once semantics. 319- Initial support for client side field level encryption. See the docstring for 320 :class:`~pymongo.mongo_client.MongoClient`, 321 :class:`~pymongo.encryption_options.AutoEncryptionOpts`, 322 and :mod:`~pymongo.encryption` for details. **Note: Support for client side 323 encryption is in beta. Backwards-breaking changes may be made before the 324 final release.** 325- Added the ``max_commit_time_ms`` parameter to 326 :meth:`~pymongo.client_session.ClientSession.start_transaction`. 327- Implement the `URI options specification`_ in the 328 :meth:`~pymongo.mongo_client.MongoClient` constructor. Consequently, there are 329 a number of changes in connection options: 330 331 - The ``tlsInsecure`` option has been added. 332 - The ``tls`` option has been added. The older ``ssl`` option has been retained 333 as an alias to the new ``tls`` option. 334 - ``wTimeout`` has been deprecated in favor of ``wTimeoutMS``. 335 - ``wTimeoutMS`` now overrides ``wTimeout`` if the user provides both. 336 - ``j`` has been deprecated in favor of ``journal``. 337 - ``journal`` now overrides ``j`` if the user provides both. 338 - ``ssl_cert_reqs`` has been deprecated in favor of ``tlsAllowInvalidCertificates``. 339 Instead of ``ssl.CERT_NONE``, ``ssl.CERT_OPTIONAL`` and ``ssl.CERT_REQUIRED``, the 340 new option expects a boolean value - ``True`` is equivalent to ``ssl.CERT_NONE``, 341 while ``False`` is equivalent to ``ssl.CERT_REQUIRED``. 342 - ``ssl_match_hostname`` has been deprecated in favor of ``tlsAllowInvalidHostnames``. 343 - ``ssl_ca_certs`` has been deprecated in favor of ``tlsCAFile``. 344 - ``ssl_certfile`` has been deprecated in favor of ``tlsCertificateKeyFile``. 345 - ``ssl_pem_passphrase`` has been deprecated in favor of ``tlsCertificateKeyFilePassword``. 346 - ``waitQueueMultiple`` has been deprecated without replacement. This option 347 was a poor solution for putting an upper bound on queuing since it didn't 348 affect queuing in other parts of the driver. 349- The ``retryWrites`` URI option now defaults to ``True``. Supported write 350 operations that fail with a retryable error will automatically be retried one 351 time, with at-most-once semantics. 352- Support for retryable reads and the ``retryReads`` URI option which is 353 enabled by default. See the :class:`~pymongo.mongo_client.MongoClient` 354 documentation for details. Now that supported operations are retried 355 automatically and transparently, users should consider adjusting any custom 356 retry logic to prevent an application from inadvertently retrying for too 357 long. 358- Support zstandard for wire protocol compression. 359- Support for periodically polling DNS SRV records to update the mongos proxy 360 list without having to change client configuration. 361- New method :meth:`pymongo.database.Database.aggregate` to support running 362 database level aggregations. 363- Support for publishing Connection Monitoring and Pooling events via the new 364 :class:`~pymongo.monitoring.ConnectionPoolListener` class. See 365 :mod:`~pymongo.monitoring` for an example. 366- :meth:`pymongo.collection.Collection.aggregate` and 367 :meth:`pymongo.database.Database.aggregate` now support the ``$merge`` pipeline 368 stage and use read preference 369 :attr:`~pymongo.read_preferences.ReadPreference.PRIMARY` if the ``$out`` or 370 ``$merge`` pipeline stages are used. 371- Support for specifying a pipeline or document in 372 :meth:`~pymongo.collection.Collection.update_one`, 373 :meth:`~pymongo.collection.Collection.update_many`, 374 :meth:`~pymongo.collection.Collection.find_one_and_update`, 375 :meth:`~pymongo.operations.UpdateOne`, and 376 :meth:`~pymongo.operations.UpdateMany`. 377- New BSON utility functions :func:`~bson.encode` and :func:`~bson.decode` 378- :class:`~bson.binary.Binary` now supports any bytes-like type that implements 379 the buffer protocol. 380- Resume tokens can now be accessed from a ``ChangeStream`` cursor using the 381 :attr:`~pymongo.change_stream.ChangeStream.resume_token` attribute. 382- Connections now survive primary step-down when using MongoDB 4.2+. 383 Applications should expect less socket connection turnover during 384 replica set elections. 385 386Unavoidable breaking changes: 387 388- Applications that use MongoDB with the MMAPv1 storage engine must now 389 explicitly disable retryable writes via the connection string 390 (e.g. ``MongoClient("mongodb://my.mongodb.cluster/db?retryWrites=false")``) or 391 the :class:`~pymongo.mongo_client.MongoClient` constructor's keyword argument 392 (e.g. ``MongoClient("mongodb://my.mongodb.cluster/db", retryWrites=False)``) 393 to avoid running into :class:`~pymongo.errors.OperationFailure` exceptions 394 during write operations. The MMAPv1 storage engine is deprecated and does 395 not support retryable writes which are now turned on by default. 396- In order to ensure that the ``connectTimeoutMS`` URI option is honored when 397 connecting to clusters with a ``mongodb+srv://`` connection string, the 398 minimum required version of the optional ``dnspython`` dependency has been 399 bumped to 1.16.0. This is a breaking change for applications that use 400 PyMongo's SRV support with a version of ``dnspython`` older than 1.16.0. 401 402.. _URI options specification: https://github.com/mongodb/specifications/blob/master/source/uri-options/uri-options.rst 403 404 405Issues Resolved 406............... 407 408See the `PyMongo 3.9 release notes in JIRA`_ for the list of resolved issues 409in this release. 410 411.. _PyMongo 3.9 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=21787 412 413Changes in Version 3.8.0 414------------------------ 415 416.. warning:: PyMongo no longer supports Python 2.6. RHEL 6 users should install 417 Python 2.7 or newer from `Red Hat Software Collections 418 <https://www.softwarecollections.org>`_. CentOS 6 users should install Python 419 2.7 or newer from `SCL 420 <https://wiki.centos.org/AdditionalResources/Repositories/SCL>`_ 421 422.. warning:: PyMongo no longer supports PyPy3 versions older than 3.5. Users 423 must upgrade to PyPy3.5+. 424 425- :class:`~bson.objectid.ObjectId` now implements the `ObjectID specification 426 version 0.2 <https://github.com/mongodb/specifications/blob/master/source/objectid.rst>`_. 427- For better performance and to better follow the GridFS spec, 428 :class:`~gridfs.grid_file.GridOut` now uses a single cursor to read all the 429 chunks in the file. Previously, each chunk in the file was queried 430 individually using :meth:`~pymongo.collection.Collection.find_one`. 431- :meth:`gridfs.grid_file.GridOut.read` now only checks for extra chunks after 432 reading the entire file. Previously, this method would check for extra 433 chunks on every call. 434- :meth:`~pymongo.database.Database.current_op` now always uses the 435 ``Database``'s :attr:`~pymongo.database.Database.codec_options` 436 when decoding the command response. Previously the codec_options 437 was only used when the MongoDB server version was <= 3.0. 438- Undeprecated :meth:`~pymongo.mongo_client.MongoClient.get_default_database` 439 and added the ``default`` parameter. 440- TLS Renegotiation is now disabled when possible. 441- Custom types can now be directly encoded to, and decoded from MongoDB using 442 the :class:`~bson.codec_options.TypeCodec` and 443 :class:`~bson.codec_options.TypeRegistry` APIs. For more information, see 444 the :doc:`custom type example <examples/custom_type>`. 445- Attempting a multi-document transaction on a sharded cluster now raises a 446 :exc:`~pymongo.errors.ConfigurationError`. 447- :meth:`pymongo.cursor.Cursor.distinct` and 448 :meth:`pymongo.cursor.Cursor.count` now send the Cursor's 449 :meth:`~pymongo.cursor.Cursor.comment` as the "comment" top-level 450 command option instead of "$comment". Also, note that "comment" must be a 451 string. 452- Add the ``filter`` parameter to 453 :meth:`~pymongo.database.Database.list_collection_names`. 454- Changes can now be requested from a ``ChangeStream`` cursor without blocking 455 indefinitely using the new 456 :meth:`pymongo.change_stream.ChangeStream.try_next` method. 457- Fixed a reference leak bug when splitting a batched write command based on 458 maxWriteBatchSize or the max message size. 459- Deprecated running find queries that set :meth:`~pymongo.cursor.Cursor.min` 460 and/or :meth:`~pymongo.cursor.Cursor.max` but do not also set a 461 :meth:`~pymongo.cursor.Cursor.hint` of which index to use. The find command 462 is expected to require a :meth:`~pymongo.cursor.Cursor.hint` when using 463 min/max starting in MongoDB 4.2. 464- Documented support for the uuidRepresentation URI option, which has been 465 supported since PyMongo 2.7. Valid values are `pythonLegacy` (the default), 466 `javaLegacy`, `csharpLegacy` and `standard`. New applications should consider 467 setting this to `standard` for cross language compatibility. 468- :class:`~bson.raw_bson.RawBSONDocument` now validates that the ``bson_bytes`` 469 passed in represent a single bson document. Earlier versions would mistakenly 470 accept multiple bson documents. 471- Iterating over a :class:`~bson.raw_bson.RawBSONDocument` now maintains the 472 same field order of the underlying raw BSON document. 473- Applications can now register a custom server selector. For more information 474 see the :doc:`server selector example <examples/server_selection>`. 475- The connection pool now implements a LIFO policy. 476 477Unavoidable breaking changes: 478 479- In order to follow the ObjectID Spec version 0.2, an ObjectId's 3-byte 480 machine identifier and 2-byte process id have been replaced with a single 481 5-byte random value generated per process. This is a breaking change for any 482 application that attempts to interpret those bytes. 483 484Issues Resolved 485............... 486 487See the `PyMongo 3.8 release notes in JIRA`_ for the list of resolved issues 488in this release. 489 490.. _PyMongo 3.8 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=19904 491 492Changes in Version 3.7.2 493------------------------ 494 495Version 3.7.2 fixes a few issues discovered since the release of 3.7.1. 496 497- Fixed a bug in retryable writes where a previous command's "txnNumber" 498 field could be sent leading to incorrect results. 499- Fixed a memory leak of a few bytes on some insert, update, or delete 500 commands when running against MongoDB 3.6+. 501- Fixed a bug that caused :meth:`pymongo.collection.Collection.ensure_index` 502 to only cache a single index per database. 503- Updated the documentation examples to use 504 :meth:`pymongo.collection.Collection.count_documents` instead of 505 :meth:`pymongo.collection.Collection.count` and 506 :meth:`pymongo.cursor.Cursor.count`. 507 508Issues Resolved 509............... 510 511See the `PyMongo 3.7.2 release notes in JIRA`_ for the list of resolved issues 512in this release. 513 514.. _PyMongo 3.7.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=21519 515 516Changes in Version 3.7.1 517------------------------ 518 519Version 3.7.1 fixes a few issues discovered since the release of 3.7.0. 520 521- Calling :meth:`~pymongo.database.Database.authenticate` more than once 522 with the same credentials results in OperationFailure. 523- Authentication fails when SCRAM-SHA-1 is used to authenticate users with 524 only MONGODB-CR credentials. 525- A millisecond rounding problem when decoding datetimes in the pure Python 526 BSON decoder on 32 bit systems and AWS lambda. 527 528Issues Resolved 529............... 530 531See the `PyMongo 3.7.1 release notes in JIRA`_ for the list of resolved issues 532in this release. 533 534.. _PyMongo 3.7.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=21096 535 536Changes in Version 3.7.0 537------------------------ 538 539Version 3.7 adds support for MongoDB 4.0. Highlights include: 540 541- Support for single replica set multi-document ACID transactions. 542 See :ref:`transactions-ref`. 543- Support for wire protocol compression. See the 544 :meth:`~pymongo.mongo_client.MongoClient` documentation for details. 545- Support for Python 3.7. 546- New count methods, :meth:`~pymongo.collection.Collection.count_documents` 547 and :meth:`~pymongo.collection.Collection.estimated_document_count`. 548 :meth:`~pymongo.collection.Collection.count_documents` is always 549 accurate when used with MongoDB 3.6+, or when used with older standalone 550 or replica set deployments. With older sharded clusters is it always 551 accurate when used with Primary read preference. It can also be used in 552 a transaction, unlike the now deprecated 553 :meth:`pymongo.collection.Collection.count` and 554 :meth:`pymongo.cursor.Cursor.count` methods. 555- Support for watching changes on all collections in a database using the 556 new :meth:`pymongo.database.Database.watch` method. 557- Support for watching changes on all collections in all databases using the 558 new :meth:`pymongo.mongo_client.MongoClient.watch` method. 559- Support for watching changes starting at a user provided timestamp using the 560 new ``start_at_operation_time`` parameter for the ``watch()`` helpers. 561- Better support for using PyMongo in a FIPS 140-2 environment. Specifically, 562 the following features and changes allow PyMongo to function when MD5 support 563 is disabled in OpenSSL by the FIPS Object Module: 564 565 - Support for the :ref:`SCRAM-SHA-256 <scram_sha_256>` 566 authentication mechanism. The :ref:`GSSAPI <gssapi>`, 567 :ref:`PLAIN <sasl_plain>`, and :ref:`MONGODB-X509 <mongodb_x509>` 568 mechanisms can also be used to avoid issues with OpenSSL in FIPS 569 environments. 570 - MD5 checksums are now optional in GridFS. See the `disable_md5` option 571 of :class:`~gridfs.GridFS` and :class:`~gridfs.GridFSBucket`. 572 - :class:`~bson.objectid.ObjectId` machine bytes are now hashed using 573 `FNV-1a 574 <https://en.wikipedia.org/wiki/Fowler-Noll-Vo_hash_function>`_ 575 instead of MD5. 576 577- The :meth:`~pymongo.database.Database.list_collection_names` and 578 :meth:`~pymongo.database.Database.collection_names` methods use 579 the nameOnly option when supported by MongoDB. 580- The :meth:`pymongo.collection.Collection.watch` method now returns an 581 instance of the :class:`~pymongo.change_stream.CollectionChangeStream` 582 class which is a subclass of :class:`~pymongo.change_stream.ChangeStream`. 583- SCRAM client and server keys are cached for improved performance, following 584 `RFC 5802 <https://tools.ietf.org/html/rfc5802>`_. 585- If not specified, the authSource for the :ref:`PLAIN <sasl_plain>` 586 authentication mechanism defaults to $external. 587- wtimeoutMS is once again supported as a URI option. 588- When using unacknowledged write concern and connected to MongoDB server 589 version 3.6 or greater, the `bypass_document_validation` option is now 590 supported in the following write helpers: 591 :meth:`~pymongo.collection.Collection.insert_one`, 592 :meth:`~pymongo.collection.Collection.replace_one`, 593 :meth:`~pymongo.collection.Collection.update_one`, 594 :meth:`~pymongo.collection.Collection.update_many`. 595 596Deprecations: 597 598- Deprecated :meth:`pymongo.collection.Collection.count` and 599 :meth:`pymongo.cursor.Cursor.count`. These two methods use the `count` 600 command and `may or may not be accurate 601 <https://docs.mongodb.com/manual/reference/command/count/#behavior>`_, 602 depending on the options used and connected MongoDB topology. Use 603 :meth:`~pymongo.collection.Collection.count_documents` instead. 604- Deprecated the snapshot option of :meth:`~pymongo.collection.Collection.find` 605 and :meth:`~pymongo.collection.Collection.find_one`. The option was 606 deprecated in MongoDB 3.6 and removed in MongoDB 4.0. 607- Deprecated the max_scan option of :meth:`~pymongo.collection.Collection.find` 608 and :meth:`~pymongo.collection.Collection.find_one`. The option was 609 deprecated in MongoDB 4.0. Use `maxTimeMS` instead. 610- Deprecated :meth:`~pymongo.mongo_client.MongoClient.close_cursor`. Use 611 :meth:`~pymongo.cursor.Cursor.close` instead. 612- Deprecated :meth:`~pymongo.mongo_client.MongoClient.database_names`. Use 613 :meth:`~pymongo.mongo_client.MongoClient.list_database_names` instead. 614- Deprecated :meth:`~pymongo.database.Database.collection_names`. Use 615 :meth:`~pymongo.database.Database.list_collection_names` instead. 616- Deprecated :meth:`~pymongo.collection.Collection.parallel_scan`. MongoDB 4.2 617 will remove the parallelCollectionScan command. 618 619Unavoidable breaking changes: 620 621- Commands that fail with server error codes 10107, 13435, 13436, 11600, 622 11602, 189, 91 (NotMaster, NotMasterNoSlaveOk, NotMasterOrSecondary, 623 InterruptedAtShutdown, InterruptedDueToReplStateChange, 624 PrimarySteppedDown, ShutdownInProgress respectively) now always raise 625 :class:`~pymongo.errors.NotMasterError` instead of 626 :class:`~pymongo.errors.OperationFailure`. 627- :meth:`~pymongo.collection.Collection.parallel_scan` no longer uses an 628 implicit session. Explicit sessions are still supported. 629- Unacknowledged writes (``w=0``) with an explicit ``session`` parameter now 630 raise a client side error. Since PyMongo does not wait for a response for an 631 unacknowledged write, two unacknowledged writes run serially by the client 632 may be executed simultaneously on the server. However, the server requires a 633 single session must not be used simultaneously by more than one operation. 634 Therefore explicit sessions cannot support unacknowledged writes. 635 Unacknowledged writes without a ``session`` parameter are still supported. 636 637 638Issues Resolved 639............... 640 641See the `PyMongo 3.7 release notes in JIRA`_ for the list of resolved issues 642in this release. 643 644.. _PyMongo 3.7 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=19287 645 646Changes in Version 3.6.1 647------------------------ 648 649Version 3.6.1 fixes bugs reported since the release of 3.6.0: 650 651- Fix regression in PyMongo 3.5.0 that causes idle sockets to be closed almost 652 instantly when ``maxIdleTimeMS`` is set. Idle sockets are now closed after 653 ``maxIdleTimeMS`` milliseconds. 654- :attr:`pymongo.mongo_client.MongoClient.max_idle_time_ms` now returns 655 milliseconds instead of seconds. 656- Properly import and use the 657 `monotonic <https://pypi.python.org/pypi/monotonic>`_ 658 library for monotonic time when it is installed. 659- :meth:`~pymongo.collection.Collection.aggregate` now ignores the 660 ``batchSize`` argument when running a pipeline with a ``$out`` stage. 661- Always send handshake metadata for new connections. 662 663Issues Resolved 664............... 665 666See the `PyMongo 3.6.1 release notes in JIRA`_ for the list of resolved issues 667in this release. 668 669.. _PyMongo 3.6.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=19438 670 671 672Changes in Version 3.6.0 673------------------------ 674 675Version 3.6 adds support for MongoDB 3.6, drops support for CPython 3.3 (PyPy3 676is still supported), and drops support for MongoDB versions older than 2.6. If 677connecting to a MongoDB 2.4 server or older, PyMongo now throws a 678:exc:`~pymongo.errors.ConfigurationError`. 679 680Highlights include: 681 682- Support for change streams. See the 683 :meth:`~pymongo.collection.Collection.watch` method for details. 684- Support for array_filters in 685 :meth:`~pymongo.collection.Collection.update_one`, 686 :meth:`~pymongo.collection.Collection.update_many`, 687 :meth:`~pymongo.collection.Collection.find_one_and_update`, 688 :meth:`~pymongo.operations.UpdateOne`, and 689 :meth:`~pymongo.operations.UpdateMany`. 690- New Session API, see :meth:`~pymongo.mongo_client.MongoClient.start_session`. 691- New methods :meth:`~pymongo.collection.Collection.find_raw_batches` and 692 :meth:`~pymongo.collection.Collection.aggregate_raw_batches` for use with 693 external libraries that can parse raw batches of BSON data. 694- New methods :meth:`~pymongo.mongo_client.MongoClient.list_databases` and 695 :meth:`~pymongo.mongo_client.MongoClient.list_database_names`. 696- New methods :meth:`~pymongo.database.Database.list_collections` and 697 :meth:`~pymongo.database.Database.list_collection_names`. 698- Support for mongodb+srv:// URIs. See 699 :class:`~pymongo.mongo_client.MongoClient` for details. 700- Index management helpers 701 (:meth:`~pymongo.collection.Collection.create_index`, 702 :meth:`~pymongo.collection.Collection.create_indexes`, 703 :meth:`~pymongo.collection.Collection.drop_index`, 704 :meth:`~pymongo.collection.Collection.drop_indexes`, 705 :meth:`~pymongo.collection.Collection.reindex`) now support maxTimeMS. 706- Support for retryable writes and the ``retryWrites`` URI option. See 707 :class:`~pymongo.mongo_client.MongoClient` for details. 708 709Deprecations: 710 711- The `useCursor` option for :meth:`~pymongo.collection.Collection.aggregate` 712 is deprecated. The option was only necessary when upgrading from MongoDB 713 2.4 to MongoDB 2.6. MongoDB 2.4 is no longer supported. 714- The :meth:`~pymongo.database.Database.add_user` and 715 :meth:`~pymongo.database.Database.remove_user` methods are deprecated. See 716 the method docstrings for alternatives. 717 718Unavoidable breaking changes: 719 720- Starting in MongoDB 3.6, the deprecated methods 721 :meth:`~pymongo.database.Database.authenticate` and 722 :meth:`~pymongo.database.Database.logout` now invalidate all cursors created 723 prior. Instead of using these methods to change credentials, pass credentials 724 for one user to the :class:`~pymongo.mongo_client.MongoClient` at construction 725 time, and either grant access to several databases to one user account, or use 726 a distinct client object for each user. 727- BSON binary subtype 4 is decoded using RFC-4122 byte order regardless 728 of the UUID representation. This is a change in behavior for applications 729 that use UUID representation :data:`bson.binary.JAVA_LEGACY` or 730 :data:`bson.binary.CSHARP_LEGACY` to decode BSON binary subtype 4. Other 731 UUID representations, :data:`bson.binary.PYTHON_LEGACY` (the default) and 732 :data:`bson.binary.STANDARD`, and the decoding of BSON binary subtype 3 733 are unchanged. 734 735 736Issues Resolved 737............... 738 739See the `PyMongo 3.6 release notes in JIRA`_ for the list of resolved issues 740in this release. 741 742.. _PyMongo 3.6 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=18043 743 744Changes in Version 3.5.1 745------------------------ 746 747Version 3.5.1 fixes bugs reported since the release of 3.5.0: 748 749- Work around socket.getsockopt issue with NetBSD. 750- :meth:`pymongo.command_cursor.CommandCursor.close` now closes 751 the cursor synchronously instead of deferring to a background 752 thread. 753- Fix documentation build warnings with Sphinx 1.6.x. 754 755Issues Resolved 756............... 757 758See the `PyMongo 3.5.1 release notes in JIRA`_ for the list of resolved issues 759in this release. 760 761.. _PyMongo 3.5.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=18721 762 763Changes in Version 3.5 764---------------------- 765 766Version 3.5 implements a number of improvements and bug fixes: 767 768Highlights include: 769 770- Username and password can be passed to 771 :class:`~pymongo.mongo_client.MongoClient` as keyword arguments. Before, the 772 only way to pass them was in the URI. 773- Increased the performance of using :class:`~bson.raw_bson.RawBSONDocument`. 774- Increased the performance of 775 :meth:`~pymongo.mongo_client.MongoClient.database_names` by using the 776 `nameOnly` option for listDatabases when available. 777- Increased the performance of 778 :meth:`~pymongo.collection.Collection.bulk_write` by reducing the memory 779 overhead of :class:`~pymongo.operations.InsertOne`, 780 :class:`~pymongo.operations.DeleteOne`, and 781 :class:`~pymongo.operations.DeleteMany`. 782- Added the `collation` option to :class:`~pymongo.operations.DeleteOne`, 783 :class:`~pymongo.operations.DeleteMany`, 784 :class:`~pymongo.operations.ReplaceOne`, 785 :class:`~pymongo.operations.UpdateOne`, and 786 :class:`~pymongo.operations.UpdateMany`. 787- Implemented the `MongoDB Extended JSON 788 <https://github.com/mongodb/specifications/blob/master/source/extended-json.rst>`_ 789 specification. 790- :class:`~bson.decimal128.Decimal128` now works when cdecimal is installed. 791- PyMongo is now tested against a wider array of operating systems and CPU 792 architectures (including s390x, ARM64, and POWER8). 793 794Changes and Deprecations: 795 796- :meth:`~pymongo.collection.Collection.find` has new options `return_key`, 797 `show_record_id`, `snapshot`, `hint`, `max_time_ms`, `max_scan`, `min`, `max`, 798 and `comment`. Deprecated the option `modifiers`. 799- Deprecated :meth:`~pymongo.collection.Collection.group`. The group command 800 was deprecated in MongoDB 3.4 and is expected to be removed in MongoDB 3.6. 801 Applications should use :meth:`~pymongo.collection.Collection.aggregate` 802 with the `$group` pipeline stage instead. 803- Deprecated :meth:`~pymongo.database.Database.authenticate`. Authenticating 804 multiple users conflicts with support for logical sessions in MongoDB 3.6. 805 To authenticate as multiple users, create multiple instances of 806 :class:`~pymongo.mongo_client.MongoClient`. 807- Deprecated :meth:`~pymongo.database.Database.eval`. The eval command 808 was deprecated in MongoDB 3.0 and will be removed in a future server version. 809- Deprecated :class:`~pymongo.database.SystemJS`. 810- Deprecated :meth:`~pymongo.mongo_client.MongoClient.get_default_database`. 811 Applications should use 812 :meth:`~pymongo.mongo_client.MongoClient.get_database` without the `name` 813 parameter instead. 814- Deprecated the MongoClient option `socketKeepAlive`. It now defaults to true 815 and disabling it is not recommended, see `does TCP keepalive time affect 816 MongoDB Deployments? 817 <https://docs.mongodb.com/manual/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments>`_ 818- Deprecated :meth:`~pymongo.collection.Collection.initialize_ordered_bulk_op`, 819 :meth:`~pymongo.collection.Collection.initialize_unordered_bulk_op`, and 820 :class:`~pymongo.bulk.BulkOperationBuilder`. Use 821 :meth:`~pymongo.collection.Collection.bulk_write` instead. 822- Deprecated :const:`~bson.json_util.STRICT_JSON_OPTIONS`. Use 823 :const:`~bson.json_util.RELAXED_JSON_OPTIONS` or 824 :const:`~bson.json_util.CANONICAL_JSON_OPTIONS` instead. 825- If a custom :class:`~bson.codec_options.CodecOptions` is passed to 826 :class:`RawBSONDocument`, its `document_class` must be 827 :class:`RawBSONDocument`. 828- :meth:`~pymongo.collection.Collection.list_indexes` no longer raises 829 OperationFailure when the collection (or database) does not exist on 830 MongoDB >= 3.0. Instead, it returns an empty 831 :class:`~pymongo.command_cursor.CommandCursor` to make the behavior 832 consistent across all MongoDB versions. 833- In Python 3, :meth:`~bson.json_util.loads` now automatically decodes JSON 834 $binary with a subtype of 0 into :class:`bytes` instead of 835 :class:`~bson.binary.Binary`. See the :doc:`/python3` for more details. 836- :meth:`~bson.json_util.loads` now raises ``TypeError`` or ``ValueError`` 837 when parsing JSON type wrappers with values of the wrong type or any 838 extra keys. 839- :meth:`pymongo.cursor.Cursor.close` and 840 :meth:`pymongo.mongo_client.MongoClient.close` 841 now kill cursors synchronously instead of deferring to a background thread. 842- :meth:`~pymongo.uri_parser.parse_uri` now returns the original value 843 of the ``readPreference`` MongoDB URI option instead of the validated read 844 preference mode. 845 846Issues Resolved 847............... 848 849See the `PyMongo 3.5 release notes in JIRA`_ for the list of resolved issues 850in this release. 851 852.. _PyMongo 3.5 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=17590 853 854Changes in Version 3.4 855---------------------- 856 857Version 3.4 implements the new server features introduced in MongoDB 3.4 858and a whole lot more: 859 860Highlights include: 861 862- Complete support for MongoDB 3.4: 863 864 - Unicode aware string comparison using :doc:`examples/collations`. 865 - Support for the new :class:`~bson.decimal128.Decimal128` BSON type. 866 - A new maxStalenessSeconds read preference option. 867 - A username is no longer required for the MONGODB-X509 authentication 868 mechanism when connected to MongoDB >= 3.4. 869 - :meth:`~pymongo.collection.Collection.parallel_scan` supports maxTimeMS. 870 - :attr:`~pymongo.write_concern.WriteConcern` is automatically 871 applied by all helpers for commands that write to the database when 872 connected to MongoDB 3.4+. This change affects the following helpers: 873 874 - :meth:`~pymongo.mongo_client.MongoClient.drop_database` 875 - :meth:`~pymongo.database.Database.create_collection` 876 - :meth:`~pymongo.database.Database.drop_collection` 877 - :meth:`~pymongo.collection.Collection.aggregate` (when using $out) 878 - :meth:`~pymongo.collection.Collection.create_indexes` 879 - :meth:`~pymongo.collection.Collection.create_index` 880 - :meth:`~pymongo.collection.Collection.drop_indexes` 881 - :meth:`~pymongo.collection.Collection.drop_indexes` 882 - :meth:`~pymongo.collection.Collection.drop_index` 883 - :meth:`~pymongo.collection.Collection.map_reduce` (when output is not 884 "inline") 885 - :meth:`~pymongo.collection.Collection.reindex` 886 - :meth:`~pymongo.collection.Collection.rename` 887 888- Improved support for logging server discovery and monitoring events. See 889 :mod:`~pymongo.monitoring` for examples. 890- Support for matching iPAddress subjectAltName values for TLS certificate 891 verification. 892- TLS compression is now explicitly disabled when possible. 893- The Server Name Indication (SNI) TLS extension is used when possible. 894- Finer control over JSON encoding/decoding with 895 :class:`~bson.json_util.JSONOptions`. 896- Allow :class:`~bson.code.Code` objects to have a scope of ``None``, 897 signifying no scope. Also allow encoding Code objects with an empty scope 898 (i.e. ``{}``). 899 900.. warning:: Starting in PyMongo 3.4, :attr:`bson.code.Code.scope` may return 901 ``None``, as the default scope is ``None`` instead of ``{}``. 902 903.. note:: PyMongo 3.4+ attempts to create sockets non-inheritable when possible 904 (i.e. it sets the close-on-exec flag on socket file descriptors). Support 905 is limited to a subset of POSIX operating systems (not including Windows) and 906 the flag usually cannot be set in a single atomic operation. CPython 3.4+ 907 implements `PEP 446`_, creating all file descriptors non-inheritable by 908 default. Users that require this behavior are encouraged to upgrade to 909 CPython 3.4+. 910 911Since 3.4rc0, the max staleness option has been renamed from ``maxStalenessMS`` 912to ``maxStalenessSeconds``, its smallest value has changed from twice 913``heartbeatFrequencyMS`` to 90 seconds, and its default value has changed from 914``None`` or 0 to -1. 915 916.. _PEP 446: https://www.python.org/dev/peps/pep-0446/ 917 918Issues Resolved 919............... 920 921See the `PyMongo 3.4 release notes in JIRA`_ for the list of resolved issues 922in this release. 923 924.. _PyMongo 3.4 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16594 925 926Changes in Version 3.3.1 927------------------------ 928 929Version 3.3.1 fixes a memory leak when decoding elements inside of a 930:class:`~bson.raw_bson.RawBSONDocument`. 931 932Issues Resolved 933............... 934 935See the `PyMongo 3.3.1 release notes in Jira`_ for the list of resolved issues 936in this release. 937 938.. _PyMongo 3.3.1 release notes in Jira: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=17636 939 940Changes in Version 3.3 941---------------------- 942 943Version 3.3 adds the following major new features: 944 945- C extensions support on big endian systems. 946- Kerberos authentication support on Windows using `WinKerberos 947 <https://pypi.python.org/pypi/winkerberos>`_. 948- A new ``ssl_clrfile`` option to support certificate revocation lists. 949- A new ``ssl_pem_passphrase`` option to support encrypted key files. 950- Support for publishing server discovery and monitoring events. See 951 :mod:`~pymongo.monitoring` for details. 952- New connection pool options ``minPoolSize`` and ``maxIdleTimeMS``. 953- New ``heartbeatFrequencyMS`` option controls the rate at which background 954 monitoring threads re-check servers. Default is once every 10 seconds. 955 956.. warning:: PyMongo 3.3 drops support for MongoDB versions older than 2.4. 957 It also drops support for python 3.2 (pypy3 continues to be supported). 958 959Issues Resolved 960............... 961 962See the `PyMongo 3.3 release notes in JIRA`_ for the list of resolved issues 963in this release. 964 965.. _PyMongo 3.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16005 966 967Changes in Version 3.2.2 968------------------------ 969 970Version 3.2.2 fixes a few issues reported since the release of 3.2.1, including 971a fix for using the `connect` option in the MongoDB URI and support for setting 972the batch size for a query to 1 when using MongoDB 3.2+. 973 974Issues Resolved 975............... 976 977See the `PyMongo 3.2.2 release notes in JIRA`_ for the list of resolved issues 978in this release. 979 980.. _PyMongo 3.2.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16538 981 982 983Changes in Version 3.2.1 984------------------------ 985 986Version 3.2.1 fixes a few issues reported since the release of 3.2, including 987running the mapreduce command twice when calling the 988:meth:`~pymongo.collection.Collection.inline_map_reduce` method and a 989:exc:`TypeError` being raised when calling 990:meth:`~gridfs.GridFSBucket.download_to_stream`. This release also 991improves error messaging around BSON decoding. 992 993Issues Resolved 994............... 995 996See the `PyMongo 3.2.1 release notes in JIRA`_ for the list of resolved issues 997in this release. 998 999.. _PyMongo 3.2.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16312 1000 1001Changes in Version 3.2 1002---------------------- 1003 1004Version 3.2 implements the new server features introduced in MongoDB 3.2. 1005 1006Highlights include: 1007 1008- Full support for MongoDB 3.2 including: 1009 1010 - Support for :class:`~pymongo.read_concern.ReadConcern` 1011 - :class:`~pymongo.write_concern.WriteConcern` is now applied to 1012 :meth:`~pymongo.collection.Collection.find_one_and_replace`, 1013 :meth:`~pymongo.collection.Collection.find_one_and_update`, and 1014 :meth:`~pymongo.collection.Collection.find_one_and_delete`. 1015 - Support for the new `bypassDocumentValidation` option in write 1016 helpers. 1017 1018- Support for reading and writing raw BSON with 1019 :class:`~bson.raw_bson.RawBSONDocument` 1020 1021.. note:: Certain :class:`~pymongo.mongo_client.MongoClient` properties now 1022 block until a connection is established or raise 1023 :exc:`~pymongo.errors.ServerSelectionTimeoutError` if no server is available. 1024 See :class:`~pymongo.mongo_client.MongoClient` for details. 1025 1026Issues Resolved 1027............... 1028 1029See the `PyMongo 3.2 release notes in JIRA`_ for the list of resolved issues 1030in this release. 1031 1032.. _PyMongo 3.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=15612 1033 1034Changes in Version 3.1.1 1035------------------------ 1036 1037Version 3.1.1 fixes a few issues reported since the release of 3.1, including a 1038regression in error handling for oversize command documents and interrupt 1039handling issues in the C extensions. 1040 1041Issues Resolved 1042............... 1043 1044See the `PyMongo 3.1.1 release notes in JIRA`_ for the list of resolved issues 1045in this release. 1046 1047.. _PyMongo 3.1.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16211 1048 1049Changes in Version 3.1 1050---------------------- 1051 1052Version 3.1 implements a few new features and fixes bugs reported since the release 1053of 3.0.3. 1054 1055Highlights include: 1056 1057- Command monitoring support. See :mod:`~pymongo.monitoring` for details. 1058- Configurable error handling for :exc:`UnicodeDecodeError`. See the 1059 `unicode_decode_error_handler` option of 1060 :class:`~bson.codec_options.CodecOptions`. 1061- Optional automatic timezone conversion when decoding BSON datetime. See the 1062 `tzinfo` option of :class:`~bson.codec_options.CodecOptions`. 1063- An implementation of :class:`~gridfs.GridFSBucket` from the new GridFS spec. 1064- Compliance with the new Connection String spec. 1065- Reduced idle CPU usage in Python 2. 1066 1067Changes in internal classes 1068........................... 1069 1070The private ``PeriodicExecutor`` class no longer takes a ``condition_class`` 1071option, and the private ``thread_util.Event`` class is removed. 1072 1073Issues Resolved 1074............... 1075 1076See the `PyMongo 3.1 release notes in JIRA`_ for the list of resolved issues 1077in this release. 1078 1079.. _PyMongo 3.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=14796 1080 1081Changes in Version 3.0.3 1082------------------------ 1083 1084Version 3.0.3 fixes issues reported since the release of 3.0.2, including a 1085feature breaking bug in the GSSAPI implementation. 1086 1087Issues Resolved 1088............... 1089 1090See the `PyMongo 3.0.3 release notes in JIRA`_ for the list of resolved issues 1091in this release. 1092 1093.. _PyMongo 3.0.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=15528 1094 1095Changes in Version 3.0.2 1096------------------------ 1097 1098Version 3.0.2 fixes issues reported since the release of 3.0.1, most 1099importantly a bug that could route operations to replica set members 1100that are not in primary or secondary state when using 1101:class:`~pymongo.read_preferences.PrimaryPreferred` or 1102:class:`~pymongo.read_preferences.Nearest`. It is a recommended upgrade for 1103all users of PyMongo 3.0.x. 1104 1105Issues Resolved 1106............... 1107 1108See the `PyMongo 3.0.2 release notes in JIRA`_ for the list of resolved issues 1109in this release. 1110 1111.. _PyMongo 3.0.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=15430 1112 1113Changes in Version 3.0.1 1114------------------------ 1115 1116Version 3.0.1 fixes issues reported since the release of 3.0, most 1117importantly a bug in GridFS.delete that could prevent file chunks from 1118actually being deleted. 1119 1120Issues Resolved 1121............... 1122 1123See the `PyMongo 3.0.1 release notes in JIRA`_ for the list of resolved issues 1124in this release. 1125 1126.. _PyMongo 3.0.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=15322 1127 1128Changes in Version 3.0 1129---------------------- 1130 1131PyMongo 3.0 is a partial rewrite of PyMongo bringing a large number of 1132improvements: 1133 1134- A unified client class. MongoClient is the one and only client class for 1135 connecting to a standalone mongod, replica set, or sharded cluster. Migrating 1136 from a standalone, to a replica set, to a sharded cluster can be accomplished 1137 with only a simple URI change. 1138- MongoClient is much more responsive to configuration changes in your MongoDB 1139 deployment. All connected servers are monitored in a non-blocking manner. 1140 Slow to respond or down servers no longer block server discovery, reducing 1141 application startup time and time to respond to new or reconfigured 1142 servers and replica set failovers. 1143- A unified CRUD API. All official MongoDB drivers now implement a standard 1144 CRUD API allowing polyglot developers to move from language to language 1145 with ease. 1146- Single source support for Python 2.x and 3.x. PyMongo no longer relies on 1147 2to3 to support Python 3. 1148- A rewritten pure Python BSON implementation, improving performance 1149 with pypy and cpython deployments without support for C extensions. 1150- Better support for greenlet based async frameworks including eventlet. 1151- Immutable client, database, and collection classes, avoiding a host of thread 1152 safety issues in client applications. 1153 1154PyMongo 3.0 brings a large number of API changes. Be sure to read the changes 1155listed below before upgrading from PyMongo 2.x. 1156 1157.. warning:: PyMongo no longer supports Python 2.4, 2.5, or 3.1. If you 1158 must use PyMongo with these versions of Python the 2.x branch of PyMongo 1159 will be minimally supported for some time. 1160 1161SONManipulator changes 1162...................... 1163 1164The :class:`~pymongo.son_manipulator.SONManipulator` API has limitations as a 1165technique for transforming your data. Instead, it is more flexible and 1166straightforward to transform outgoing documents in your own code before passing 1167them to PyMongo, and transform incoming documents after receiving them from 1168PyMongo. 1169 1170Thus the :meth:`~pymongo.database.Database.add_son_manipulator` method is 1171deprecated. PyMongo 3's new CRUD API does **not** apply SON manipulators to 1172documents passed to :meth:`~pymongo.collection.Collection.bulk_write`, 1173:meth:`~pymongo.collection.Collection.insert_one`, 1174:meth:`~pymongo.collection.Collection.insert_many`, 1175:meth:`~pymongo.collection.Collection.update_one`, or 1176:meth:`~pymongo.collection.Collection.update_many`. SON manipulators are **not** 1177applied to documents returned by the new methods 1178:meth:`~pymongo.collection.Collection.find_one_and_delete`, 1179:meth:`~pymongo.collection.Collection.find_one_and_replace`, and 1180:meth:`~pymongo.collection.Collection.find_one_and_update`. 1181 1182SSL/TLS changes 1183............... 1184 1185When `ssl` is ``True`` the `ssl_cert_reqs` option now defaults to 1186:attr:`ssl.CERT_REQUIRED` if not provided. PyMongo will attempt to load OS 1187provided CA certificates to verify the server, raising 1188:exc:`~pymongo.errors.ConfigurationError` if it cannot. 1189 1190Gevent Support 1191.............. 1192 1193In previous versions, PyMongo supported Gevent in two modes: you could call 1194``gevent.monkey.patch_socket()`` and pass ``use_greenlets=True`` to 1195:class:`~pymongo.mongo_client.MongoClient`, or you could simply call 1196``gevent.monkey.patch_all()`` and omit the ``use_greenlets`` argument. 1197 1198In PyMongo 3.0, the ``use_greenlets`` option is gone. To use PyMongo with 1199Gevent simply call ``gevent.monkey.patch_all()``. 1200 1201For more information, 1202see :doc:`PyMongo's Gevent documentation <examples/gevent>`. 1203 1204:class:`~pymongo.mongo_client.MongoClient` changes 1205.................................................. 1206 1207:class:`~pymongo.mongo_client.MongoClient` is now the one and only 1208client class for a standalone server, mongos, or replica set. 1209It includes the functionality that had been split into 1210``MongoReplicaSetClient``: it can connect to a replica set, discover all its 1211members, and monitor the set for stepdowns, elections, and reconfigs. 1212:class:`~pymongo.mongo_client.MongoClient` now also supports the full 1213:class:`~pymongo.read_preferences.ReadPreference` API. 1214 1215The obsolete classes ``MasterSlaveConnection``, ``Connection``, and 1216``ReplicaSetConnection`` are removed. 1217 1218The :class:`~pymongo.mongo_client.MongoClient` constructor no 1219longer blocks while connecting to the server or servers, and it no 1220longer raises :class:`~pymongo.errors.ConnectionFailure` if they 1221are unavailable, nor :class:`~pymongo.errors.ConfigurationError` 1222if the user's credentials are wrong. Instead, the constructor 1223returns immediately and launches the connection process on 1224background threads. The ``connect`` option is added to control whether 1225these threads are started immediately, or when the client is first used. 1226 1227Therefore the ``alive`` method is removed since it no longer provides meaningful 1228information; even if the client is disconnected, it may discover a server in 1229time to fulfill the next operation. 1230 1231In PyMongo 2.x, :class:`~pymongo.mongo_client.MongoClient` accepted a list of 1232standalone MongoDB servers and used the first it could connect to:: 1233 1234 MongoClient(['host1.com:27017', 'host2.com:27017']) 1235 1236A list of multiple standalones is no longer supported; if multiple servers 1237are listed they must be members of the same replica set, or mongoses in the 1238same sharded cluster. 1239 1240The behavior for a list of mongoses is changed from "high availability" to 1241"load balancing". Before, the client connected to the lowest-latency mongos in 1242the list, and used it until a network error prompted it to re-evaluate all 1243mongoses' latencies and reconnect to one of them. In PyMongo 3, the client 1244monitors its network latency to all the mongoses continuously, and distributes 1245operations evenly among those with the lowest latency. 1246See :ref:`mongos-load-balancing` for more information. 1247 1248The client methods ``start_request``, ``in_request``, and ``end_request`` 1249are removed, and so is the ``auto_start_request`` option. Requests were 1250designed to make read-your-writes consistency more likely with the ``w=0`` 1251write concern. Additionally, a thread in a request used the same member for 1252all secondary reads in a replica set. To ensure read-your-writes consistency 1253in PyMongo 3.0, do not override the default write concern with ``w=0``, and 1254do not override the default :ref:`read preference <secondary-reads>` of 1255PRIMARY. 1256 1257Support for the ``slaveOk`` (or ``slave_okay``), ``safe``, and 1258``network_timeout`` options has been removed. Use 1259:attr:`~pymongo.read_preferences.ReadPreference.SECONDARY_PREFERRED` instead of 1260slave_okay. Accept the default write concern, acknowledged writes, instead of 1261setting safe=True. Use socketTimeoutMS in place of network_timeout (note that 1262network_timeout was in seconds, where as socketTimeoutMS is milliseconds). 1263 1264The ``max_pool_size`` option has been removed. It is replaced by the 1265``maxPoolSize`` MongoDB URI option. ``maxPoolSize`` is now a supported URI 1266option in PyMongo and can be passed as a keyword argument. 1267 1268The ``copy_database`` method is removed, see the 1269:doc:`copy_database examples </examples/copydb>` for alternatives. 1270 1271The ``disconnect`` method is removed. Use 1272:meth:`~pymongo.mongo_client.MongoClient.close` instead. 1273 1274The ``get_document_class`` method is removed. Use 1275:attr:`~pymongo.mongo_client.MongoClient.codec_options` instead. 1276 1277The ``get_lasterror_options``, ``set_lasterror_options``, and 1278``unset_lasterror_options`` methods are removed. Write concern options 1279can be passed to :class:`~pymongo.mongo_client.MongoClient` as keyword 1280arguments or MongoDB URI options. 1281 1282The :meth:`~pymongo.mongo_client.MongoClient.get_database` method is added for 1283getting a Database instance with its options configured differently than the 1284MongoClient's. 1285 1286The following read-only attributes have been added: 1287 1288- :attr:`~pymongo.mongo_client.MongoClient.codec_options` 1289 1290The following attributes are now read-only: 1291 1292- :attr:`~pymongo.mongo_client.MongoClient.read_preference` 1293- :attr:`~pymongo.mongo_client.MongoClient.write_concern` 1294 1295The following attributes have been removed: 1296 1297- :attr:`~pymongo.mongo_client.MongoClient.document_class` 1298 (use :attr:`~pymongo.mongo_client.MongoClient.codec_options` instead) 1299- :attr:`~pymongo.mongo_client.MongoClient.host` 1300 (use :attr:`~pymongo.mongo_client.MongoClient.address` instead) 1301- :attr:`~pymongo.mongo_client.MongoClient.min_wire_version` 1302- :attr:`~pymongo.mongo_client.MongoClient.max_wire_version` 1303- :attr:`~pymongo.mongo_client.MongoClient.port` 1304 (use :attr:`~pymongo.mongo_client.MongoClient.address` instead) 1305- :attr:`~pymongo.mongo_client.MongoClient.safe` 1306 (use :attr:`~pymongo.mongo_client.MongoClient.write_concern` instead) 1307- :attr:`~pymongo.mongo_client.MongoClient.slave_okay` 1308 (use :attr:`~pymongo.mongo_client.MongoClient.read_preference` instead) 1309- :attr:`~pymongo.mongo_client.MongoClient.tag_sets` 1310 (use :attr:`~pymongo.mongo_client.MongoClient.read_preference` instead) 1311- :attr:`~pymongo.mongo_client.MongoClient.tz_aware` 1312 (use :attr:`~pymongo.mongo_client.MongoClient.codec_options` instead) 1313 1314The following attributes have been renamed: 1315 1316- :attr:`~pymongo.mongo_client.MongoClient.secondary_acceptable_latency_ms` is 1317 now :attr:`~pymongo.mongo_client.MongoClient.local_threshold_ms` and is now 1318 read-only. 1319 1320:class:`~pymongo.cursor.Cursor` changes 1321....................................... 1322 1323The ``conn_id`` property is renamed to :attr:`~pymongo.cursor.Cursor.address`. 1324 1325Cursor management changes 1326......................... 1327 1328:class:`~pymongo.cursor_manager.CursorManager` and 1329:meth:`~pymongo.mongo_client.MongoClient.set_cursor_manager` are no longer 1330deprecated. If you subclass :class:`~pymongo.cursor_manager.CursorManager` 1331your implementation of :meth:`~pymongo.cursor_manager.CursorManager.close` 1332must now take a second parameter, `address`. The ``BatchCursorManager`` class 1333is removed. 1334 1335The second parameter to :meth:`~pymongo.mongo_client.MongoClient.close_cursor` 1336is renamed from ``_conn_id`` to ``address``. 1337:meth:`~pymongo.mongo_client.MongoClient.kill_cursors` now accepts an `address` 1338parameter. 1339 1340:class:`~pymongo.database.Database` changes 1341........................................... 1342 1343The ``connection`` property is renamed to 1344:attr:`~pymongo.database.Database.client`. 1345 1346The following read-only attributes have been added: 1347 1348- :attr:`~pymongo.database.Database.codec_options` 1349 1350The following attributes are now read-only: 1351 1352- :attr:`~pymongo.database.Database.read_preference` 1353- :attr:`~pymongo.database.Database.write_concern` 1354 1355Use :meth:`~pymongo.mongo_client.MongoClient.get_database` for getting a 1356Database instance with its options configured differently than the 1357MongoClient's. 1358 1359The following attributes have been removed: 1360 1361- :attr:`~pymongo.database.Database.safe` 1362- :attr:`~pymongo.database.Database.secondary_acceptable_latency_ms` 1363- :attr:`~pymongo.database.Database.slave_okay` 1364- :attr:`~pymongo.database.Database.tag_sets` 1365 1366The following methods have been added: 1367 1368- :meth:`~pymongo.database.Database.get_collection` 1369 1370The following methods have been changed: 1371 1372- :meth:`~pymongo.database.Database.command`. Support for `as_class`, 1373 `uuid_subtype`, `tag_sets`, and `secondary_acceptable_latency_ms` have been 1374 removed. You can instead pass an instance of 1375 :class:`~bson.codec_options.CodecOptions` as `codec_options` and an instance 1376 of a read preference class from :mod:`~pymongo.read_preferences` as 1377 `read_preference`. The `fields` and `compile_re` options are also removed. 1378 The `fields` options was undocumented and never really worked. Regular 1379 expressions are always decoded to :class:`~bson.regex.Regex`. 1380 1381The following methods have been deprecated: 1382 1383- :meth:`~pymongo.database.Database.add_son_manipulator` 1384 1385The following methods have been removed: 1386 1387The ``get_lasterror_options``, ``set_lasterror_options``, and 1388``unset_lasterror_options`` methods have been removed. Use 1389:class:`~pymongo.write_concern.WriteConcern` with 1390:meth:`~pymongo.mongo_client.MongoClient.get_database` instead. 1391 1392:class:`~pymongo.collection.Collection` changes 1393............................................... 1394 1395The following read-only attributes have been added: 1396 1397- :attr:`~pymongo.collection.Collection.codec_options` 1398 1399The following attributes are now read-only: 1400 1401- :attr:`~pymongo.collection.Collection.read_preference` 1402- :attr:`~pymongo.collection.Collection.write_concern` 1403 1404Use :meth:`~pymongo.database.Database.get_collection` or 1405:meth:`~pymongo.collection.Collection.with_options` for getting a Collection 1406instance with its options configured differently than the Database's. 1407 1408The following attributes have been removed: 1409 1410- :attr:`~pymongo.collection.Collection.safe` 1411- :attr:`~pymongo.collection.Collection.secondary_acceptable_latency_ms` 1412- :attr:`~pymongo.collection.Collection.slave_okay` 1413- :attr:`~pymongo.collection.Collection.tag_sets` 1414 1415The following methods have been added: 1416 1417- :meth:`~pymongo.collection.Collection.bulk_write` 1418- :meth:`~pymongo.collection.Collection.insert_one` 1419- :meth:`~pymongo.collection.Collection.insert_many` 1420- :meth:`~pymongo.collection.Collection.update_one` 1421- :meth:`~pymongo.collection.Collection.update_many` 1422- :meth:`~pymongo.collection.Collection.replace_one` 1423- :meth:`~pymongo.collection.Collection.delete_one` 1424- :meth:`~pymongo.collection.Collection.delete_many` 1425- :meth:`~pymongo.collection.Collection.find_one_and_delete` 1426- :meth:`~pymongo.collection.Collection.find_one_and_replace` 1427- :meth:`~pymongo.collection.Collection.find_one_and_update` 1428- :meth:`~pymongo.collection.Collection.with_options` 1429- :meth:`~pymongo.collection.Collection.create_indexes` 1430- :meth:`~pymongo.collection.Collection.list_indexes` 1431 1432The following methods have changed: 1433 1434- :meth:`~pymongo.collection.Collection.aggregate` now **always** returns an 1435 instance of :class:`~pymongo.command_cursor.CommandCursor`. See the 1436 documentation for all options. 1437- :meth:`~pymongo.collection.Collection.count` now optionally takes a filter 1438 argument, as well as other options supported by the count command. 1439- :meth:`~pymongo.collection.Collection.distinct` now optionally takes a filter 1440 argument. 1441- :meth:`~pymongo.collection.Collection.create_index` no longer caches 1442 indexes, therefore the `cache_for` parameter has been removed. It also 1443 no longer supports the `bucket_size` and `drop_dups` aliases for `bucketSize` 1444 and `dropDups`. 1445 1446The following methods are deprecated: 1447 1448- :meth:`~pymongo.collection.Collection.save` 1449- :meth:`~pymongo.collection.Collection.insert` 1450- :meth:`~pymongo.collection.Collection.update` 1451- :meth:`~pymongo.collection.Collection.remove` 1452- :meth:`~pymongo.collection.Collection.find_and_modify` 1453- :meth:`~pymongo.collection.Collection.ensure_index` 1454 1455The following methods have been removed: 1456 1457The ``get_lasterror_options``, ``set_lasterror_options``, and 1458``unset_lasterror_options`` methods have been removed. Use 1459:class:`~pymongo.write_concern.WriteConcern` with 1460:meth:`~pymongo.collection.Collection.with_options` instead. 1461 1462Changes to :meth:`~pymongo.collection.Collection.find` and :meth:`~pymongo.collection.Collection.find_one` 1463`````````````````````````````````````````````````````````````````````````````````````````````````````````` 1464 1465The following find/find_one options have been renamed: 1466 1467These renames only affect your code if you passed these as keyword arguments, 1468like find(fields=['fieldname']). If you passed only positional parameters these 1469changes are not significant for your application. 1470 1471- spec -> filter 1472- fields -> projection 1473- partial -> allow_partial_results 1474 1475The following find/find_one options have been added: 1476 1477- cursor_type (see :class:`~pymongo.cursor.CursorType` for values) 1478- oplog_replay 1479- modifiers 1480 1481The following find/find_one options have been removed: 1482 1483- network_timeout (use :meth:`~pymongo.cursor.Cursor.max_time_ms` instead) 1484- slave_okay (use one of the read preference classes from 1485 :mod:`~pymongo.read_preferences` and 1486 :meth:`~pymongo.collection.Collection.with_options` instead) 1487- read_preference (use :meth:`~pymongo.collection.Collection.with_options` 1488 instead) 1489- tag_sets (use one of the read preference classes from 1490 :mod:`~pymongo.read_preferences` and 1491 :meth:`~pymongo.collection.Collection.with_options` instead) 1492- secondary_acceptable_latency_ms (use the `localThresholdMS` URI option 1493 instead) 1494- max_scan (use the new `modifiers` option instead) 1495- snapshot (use the new `modifiers` option instead) 1496- tailable (use the new `cursor_type` option instead) 1497- await_data (use the new `cursor_type` option instead) 1498- exhaust (use the new `cursor_type` option instead) 1499- as_class (use :meth:`~pymongo.collection.Collection.with_options` with 1500 :class:`~bson.codec_options.CodecOptions` instead) 1501- compile_re (BSON regular expressions are always decoded to 1502 :class:`~bson.regex.Regex`) 1503 1504The following find/find_one options are deprecated: 1505 1506- manipulate 1507 1508The following renames need special handling. 1509 1510- timeout -> no_cursor_timeout - 1511 The default for `timeout` was True. The default for `no_cursor_timeout` is 1512 False. If you were previously passing False for `timeout` you must pass 1513 **True** for `no_cursor_timeout` to keep the previous behavior. 1514 1515:mod:`~pymongo.errors` changes 1516.............................. 1517 1518The exception classes ``UnsupportedOption`` and ``TimeoutError`` are deleted. 1519 1520:mod:`~gridfs` changes 1521...................... 1522 1523Since PyMongo 1.6, methods ``open`` and ``close`` of :class:`~gridfs.GridFS` 1524raised an ``UnsupportedAPI`` exception, as did the entire ``GridFile`` class. 1525The unsupported methods, the class, and the exception are all deleted. 1526 1527:mod:`~bson` changes 1528.................... 1529 1530The `compile_re` option is removed from all methods 1531that accepted it in :mod:`~bson` and :mod:`~bson.json_util`. Additionally, it 1532is removed from :meth:`~pymongo.collection.Collection.find`, 1533:meth:`~pymongo.collection.Collection.find_one`, 1534:meth:`~pymongo.collection.Collection.aggregate`, 1535:meth:`~pymongo.database.Database.command`, and so on. 1536PyMongo now always represents BSON regular expressions as 1537:class:`~bson.regex.Regex` objects. This prevents errors for incompatible 1538patterns, see `PYTHON-500`_. Use :meth:`~bson.regex.Regex.try_compile` to 1539attempt to convert from a BSON regular expression to a Python regular 1540expression object. 1541 1542PyMongo now decodes the int64 BSON type to :class:`~bson.int64.Int64`, a 1543trivial wrapper around long (in python 2.x) or int (in python 3.x). This 1544allows BSON int64 to be round tripped without losing type information in 1545python 3. Note that if you store a python long (or a python int larger than 15464 bytes) it will be returned from PyMongo as :class:`~bson.int64.Int64`. 1547 1548The `as_class`, `tz_aware`, and `uuid_subtype` options are removed from all 1549BSON encoding and decoding methods. Use 1550:class:`~bson.codec_options.CodecOptions` to configure these options. The 1551APIs affected are: 1552 1553- :func:`~bson.decode_all` 1554- :func:`~bson.decode_iter` 1555- :func:`~bson.decode_file_iter` 1556- :meth:`~bson.BSON.encode` 1557- :meth:`~bson.BSON.decode` 1558 1559This is a breaking change for any application that uses the BSON API directly 1560and changes any of the named parameter defaults. No changes are required for 1561applications that use the default values for these options. The behavior 1562remains the same. 1563 1564.. _PYTHON-500: https://jira.mongodb.org/browse/PYTHON-500 1565 1566Issues Resolved 1567............... 1568 1569See the `PyMongo 3.0 release notes in JIRA`_ for the list of resolved issues 1570in this release. 1571 1572.. _PyMongo 3.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=12501 1573 1574Changes in Version 2.9.5 1575------------------------ 1576 1577Version 2.9.5 works around ssl module deprecations in Python 3.6, and expected 1578future ssl module deprecations. It also fixes bugs found since the release of 15792.9.4. 1580 1581- Use ssl.SSLContext and ssl.PROTOCOL_TLS_CLIENT when available. 1582- Fixed a C extensions build issue when the interpreter was built with -std=c99 1583- Fixed various build issues with MinGW32. 1584- Fixed a write concern bug in :meth:`~pymongo.database.Database.add_user` and 1585 :meth:`~pymongo.database.Database.remove_user` when connected to MongoDB 3.2+ 1586- Fixed various test failures related to changes in gevent, MongoDB, and our CI 1587 test environment. 1588 1589Issues Resolved 1590............... 1591 1592See the `PyMongo 2.9.5 release notes in JIRA`_ for the list of resolved issues 1593in this release. 1594 1595.. _PyMongo 2.9.5 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=17605 1596 1597Changes in Version 2.9.4 1598------------------------ 1599 1600Version 2.9.4 fixes issues reported since the release of 2.9.3. 1601 1602- Fixed __repr__ for closed instances of :class:`~pymongo.mongo_client.MongoClient`. 1603- Fixed :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient` handling of 1604 uuidRepresentation. 1605- Fixed building and testing the documentation with python 3.x. 1606- New documentation for :doc:`examples/tls` and :doc:`atlas`. 1607 1608Issues Resolved 1609............... 1610 1611See the `PyMongo 2.9.4 release notes in JIRA`_ for the list of resolved issues 1612in this release. 1613 1614.. _PyMongo 2.9.4 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16885 1615 1616Changes in Version 2.9.3 1617------------------------ 1618 1619Version 2.9.3 fixes a few issues reported since the release of 2.9.2 including 1620thread safety issues in :meth:`~pymongo.collection.Collection.ensure_index`, 1621:meth:`~pymongo.collection.Collection.drop_index`, and 1622:meth:`~pymongo.collection.Collection.drop_indexes`. 1623 1624Issues Resolved 1625............... 1626 1627See the `PyMongo 2.9.3 release notes in JIRA`_ for the list of resolved issues 1628in this release. 1629 1630.. _PyMongo 2.9.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16539 1631 1632Changes in Version 2.9.2 1633------------------------ 1634 1635Version 2.9.2 restores Python 3.1 support, which was broken in PyMongo 2.8. It 1636improves an error message when decoding BSON as well as fixes a couple other 1637issues including :meth:`~pymongo.collection.Collection.aggregate` ignoring 1638:attr:`~pymongo.collection.Collection.codec_options` and 1639:meth:`~pymongo.database.Database.command` raising a superfluous 1640`DeprecationWarning`. 1641 1642Issues Resolved 1643............... 1644 1645See the `PyMongo 2.9.2 release notes in JIRA`_ for the list of resolved issues 1646in this release. 1647 1648.. _PyMongo 2.9.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16303 1649 1650Changes in Version 2.9.1 1651------------------------ 1652 1653Version 2.9.1 fixes two interrupt handling issues in the C extensions and 1654adapts a test case for a behavior change in MongoDB 3.2. 1655 1656Issues Resolved 1657............... 1658 1659See the `PyMongo 2.9.1 release notes in JIRA`_ for the list of resolved issues 1660in this release. 1661 1662.. _PyMongo 2.9.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=16208 1663 1664Changes in Version 2.9 1665---------------------- 1666 1667Version 2.9 provides an upgrade path to PyMongo 3.x. Most of the API changes 1668from PyMongo 3.0 have been backported in a backward compatible way, allowing 1669applications to be written against PyMongo >= 2.9, rather then PyMongo 2.x or 1670PyMongo 3.x. See the :doc:`/migrate-to-pymongo3` for detailed examples. 1671 1672.. note:: There are a number of new deprecations in this release for features 1673 that were removed in PyMongo 3.0. 1674 1675 :class:`~pymongo.mongo_client.MongoClient`: 1676 - :attr:`~pymongo.mongo_client.MongoClient.host` 1677 - :attr:`~pymongo.mongo_client.MongoClient.port` 1678 - :attr:`~pymongo.mongo_client.MongoClient.use_greenlets` 1679 - :attr:`~pymongo.mongo_client.MongoClient.document_class` 1680 - :attr:`~pymongo.mongo_client.MongoClient.tz_aware` 1681 - :attr:`~pymongo.mongo_client.MongoClient.secondary_acceptable_latency_ms` 1682 - :attr:`~pymongo.mongo_client.MongoClient.tag_sets` 1683 - :attr:`~pymongo.mongo_client.MongoClient.uuid_subtype` 1684 - :meth:`~pymongo.mongo_client.MongoClient.disconnect` 1685 - :meth:`~pymongo.mongo_client.MongoClient.alive` 1686 1687 :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`: 1688 - :attr:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.use_greenlets` 1689 - :attr:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.document_class` 1690 - :attr:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.tz_aware` 1691 - :attr:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.secondary_acceptable_latency_ms` 1692 - :attr:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.tag_sets` 1693 - :attr:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.uuid_subtype` 1694 - :meth:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.alive` 1695 1696 :class:`~pymongo.database.Database`: 1697 - :attr:`~pymongo.database.Database.secondary_acceptable_latency_ms` 1698 - :attr:`~pymongo.database.Database.tag_sets` 1699 - :attr:`~pymongo.database.Database.uuid_subtype` 1700 1701 :class:`~pymongo.collection.Collection`: 1702 - :attr:`~pymongo.collection.Collection.secondary_acceptable_latency_ms` 1703 - :attr:`~pymongo.collection.Collection.tag_sets` 1704 - :attr:`~pymongo.collection.Collection.uuid_subtype` 1705 1706.. warning:: 1707 In previous versions of PyMongo, changing the value of 1708 :attr:`~pymongo.mongo_client.MongoClient.document_class` changed 1709 the behavior of all existing instances of 1710 :class:`~pymongo.collection.Collection`:: 1711 1712 >>> coll = client.test.test 1713 >>> coll.find_one() 1714 {u'_id': ObjectId('5579dc7cfba5220cc14d9a18')} 1715 >>> from bson.son import SON 1716 >>> client.document_class = SON 1717 >>> coll.find_one() 1718 SON([(u'_id', ObjectId('5579dc7cfba5220cc14d9a18'))]) 1719 1720 The document_class setting is now configurable at the client, 1721 database, collection, and per-operation level. This required breaking 1722 the existing behavior. To change the document class per operation in a 1723 forward compatible way use 1724 :meth:`~pymongo.collection.Collection.with_options`:: 1725 1726 >>> coll.find_one() 1727 {u'_id': ObjectId('5579dc7cfba5220cc14d9a18')} 1728 >>> from bson.codec_options import CodecOptions 1729 >>> coll.with_options(CodecOptions(SON)).find_one() 1730 SON([(u'_id', ObjectId('5579dc7cfba5220cc14d9a18'))]) 1731 1732Issues Resolved 1733............... 1734 1735See the `PyMongo 2.9 release notes in JIRA`_ for the list of resolved issues 1736in this release. 1737 1738.. _PyMongo 2.9 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=14795 1739 1740Changes in Version 2.8.1 1741------------------------ 1742 1743Version 2.8.1 fixes a number of issues reported since the release of PyMongo 17442.8. It is a recommended upgrade for all users of PyMongo 2.x. 1745 1746Issues Resolved 1747............... 1748 1749See the `PyMongo 2.8.1 release notes in JIRA`_ for the list of resolved issues 1750in this release. 1751 1752.. _PyMongo 2.8.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=15324 1753 1754Changes in Version 2.8 1755---------------------- 1756 1757Version 2.8 is a major release that provides full support for MongoDB 3.0 and 1758fixes a number of bugs. 1759 1760Special thanks to Don Mitchell, Ximing, Can Zhang, Sergey Azovskov, and Heewa 1761Barfchin for their contributions to this release. 1762 1763Highlights include: 1764 1765- Support for the SCRAM-SHA-1 authentication mechanism (new in MongoDB 3.0). 1766- JSON decoder support for the new $numberLong and $undefined types. 1767- JSON decoder support for the $date type as an ISO-8601 string. 1768- Support passing an index name to :meth:`~pymongo.cursor.Cursor.hint`. 1769- The :meth:`~pymongo.cursor.Cursor.count` method will use a hint if one 1770 has been provided through :meth:`~pymongo.cursor.Cursor.hint`. 1771- A new socketKeepAlive option for the connection pool. 1772- New generator based BSON decode functions, :func:`~bson.decode_iter` 1773 and :func:`~bson.decode_file_iter`. 1774- Internal changes to support alternative storage engines like wiredtiger. 1775 1776.. note:: There are a number of deprecations in this release for features that 1777 will be removed in PyMongo 3.0. These include: 1778 1779 - :meth:`~pymongo.mongo_client.MongoClient.start_request` 1780 - :meth:`~pymongo.mongo_client.MongoClient.in_request` 1781 - :meth:`~pymongo.mongo_client.MongoClient.end_request` 1782 - :meth:`~pymongo.mongo_client.MongoClient.copy_database` 1783 - :meth:`~pymongo.database.Database.error` 1784 - :meth:`~pymongo.database.Database.last_status` 1785 - :meth:`~pymongo.database.Database.previous_error` 1786 - :meth:`~pymongo.database.Database.reset_error_history` 1787 - :class:`~pymongo.master_slave_connection.MasterSlaveConnection` 1788 1789 The JSON format for :class:`~bson.timestamp.Timestamp` has changed from 1790 '{"t": <int>, "i": <int>}' to '{"$timestamp": {"t": <int>, "i": <int>}}'. 1791 This new format will be decoded to an instance of 1792 :class:`~bson.timestamp.Timestamp`. The old format will continue to be 1793 decoded to a python dict as before. Encoding to the old format is no 1794 longer supported as it was never correct and loses type information. 1795 1796Issues Resolved 1797............... 1798 1799See the `PyMongo 2.8 release notes in JIRA`_ for the list of resolved issues 1800in this release. 1801 1802.. _PyMongo 2.8 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=14223 1803 1804Changes in Version 2.7.2 1805------------------------ 1806 1807Version 2.7.2 includes fixes for upsert reporting in the bulk API for MongoDB 1808versions previous to 2.6, a regression in how son manipulators are applied in 1809:meth:`~pymongo.collection.Collection.insert`, a few obscure connection pool 1810semaphore leaks, and a few other minor issues. See the list of issues resolved 1811for full details. 1812 1813Issues Resolved 1814............... 1815 1816See the `PyMongo 2.7.2 release notes in JIRA`_ for the list of resolved issues 1817in this release. 1818 1819.. _PyMongo 2.7.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=14005 1820 1821Changes in Version 2.7.1 1822------------------------ 1823 1824Version 2.7.1 fixes a number of issues reported since the release of 2.7, 1825most importantly a fix for creating indexes and manipulating users through 1826mongos versions older than 2.4.0. 1827 1828Issues Resolved 1829............... 1830 1831See the `PyMongo 2.7.1 release notes in JIRA`_ for the list of resolved issues 1832in this release. 1833 1834.. _PyMongo 2.7.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=13823 1835 1836Changes in Version 2.7 1837---------------------- 1838 1839PyMongo 2.7 is a major release with a large number of new features and bug 1840fixes. Highlights include: 1841 1842- Full support for MongoDB 2.6. 1843- A new :doc:`bulk write operations API </examples/bulk>`. 1844- Support for server side query timeouts using 1845 :meth:`~pymongo.cursor.Cursor.max_time_ms`. 1846- Support for writing :meth:`~pymongo.collection.Collection.aggregate` 1847 output to a collection. 1848- A new :meth:`~pymongo.collection.Collection.parallel_scan` helper. 1849- :class:`~pymongo.errors.OperationFailure` and its subclasses now include 1850 a :attr:`~pymongo.errors.OperationFailure.details` attribute with complete 1851 error details from the server. 1852- A new GridFS :meth:`~gridfs.GridFS.find` method that returns a 1853 :class:`~gridfs.grid_file.GridOutCursor`. 1854- Greatly improved :doc:`support for mod_wsgi </examples/mod_wsgi>` when using 1855 PyMongo's C extensions. Read `Jesse's blog post 1856 <http://emptysqua.re/blog/python-c-extensions-and-mod-wsgi/>`_ for details. 1857- Improved C extension support for ARM little endian. 1858 1859Breaking changes 1860................ 1861 1862Version 2.7 drops support for replica sets running MongoDB versions older 1863than 1.6.2. 1864 1865Issues Resolved 1866............... 1867 1868See the `PyMongo 2.7 release notes in JIRA`_ for the list of resolved issues 1869in this release. 1870 1871.. _PyMongo 2.7 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=12892 1872 1873Changes in Version 2.6.3 1874------------------------ 1875 1876Version 2.6.3 fixes issues reported since the release of 2.6.2, most 1877importantly a semaphore leak when a connection to the server fails. 1878 1879Issues Resolved 1880............... 1881 1882See the `PyMongo 2.6.3 release notes in JIRA`_ for the list of resolved issues 1883in this release. 1884 1885.. _PyMongo 2.6.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=13098 1886 1887Changes in Version 2.6.2 1888------------------------ 1889 1890Version 2.6.2 fixes a :exc:`TypeError` problem when max_pool_size=None 1891is used in Python 3. 1892 1893Issues Resolved 1894............... 1895 1896See the `PyMongo 2.6.2 release notes in JIRA`_ for the list of resolved issues 1897in this release. 1898 1899.. _PyMongo 2.6.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=12910 1900 1901Changes in Version 2.6.1 1902------------------------ 1903 1904Version 2.6.1 fixes a reference leak in 1905the :meth:`~pymongo.collection.Collection.insert` method. 1906 1907Issues Resolved 1908............... 1909 1910See the `PyMongo 2.6.1 release notes in JIRA`_ for the list of resolved issues 1911in this release. 1912 1913.. _PyMongo 2.6.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=12905 1914 1915Changes in Version 2.6 1916---------------------- 1917 1918Version 2.6 includes some frequently requested improvements and adds 1919support for some early MongoDB 2.6 features. 1920 1921Special thanks go to Justin Patrin for his work on the connection pool 1922in this release. 1923 1924Important new features: 1925 1926- The ``max_pool_size`` option for :class:`~pymongo.mongo_client.MongoClient` 1927 and :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient` now 1928 actually caps the number of sockets the pool will open concurrently. 1929 Once the pool has reached :attr:`~pymongo.mongo_client.MongoClient.max_pool_size` 1930 operations will block waiting for a socket to become available. If 1931 ``waitQueueTimeoutMS`` is set, an operation that blocks waiting for a socket 1932 will raise :exc:`~pymongo.errors.ConnectionFailure` after the timeout. By 1933 default ``waitQueueTimeoutMS`` is not set. 1934 See :ref:`connection-pooling` for more information. 1935- The :meth:`~pymongo.collection.Collection.insert` method automatically splits 1936 large batches of documents into multiple insert messages based on 1937 :attr:`~pymongo.mongo_client.MongoClient.max_message_size` 1938- Support for the exhaust cursor flag. 1939 See :meth:`~pymongo.collection.Collection.find` for details and caveats. 1940- Support for the PLAIN and MONGODB-X509 authentication mechanisms. 1941 See :doc:`the authentication docs </examples/authentication>` for more 1942 information. 1943- Support aggregation output as a :class:`~pymongo.cursor.Cursor`. See 1944 :meth:`~pymongo.collection.Collection.aggregate` for details. 1945 1946.. warning:: SIGNIFICANT BEHAVIOR CHANGE in 2.6. Previously, `max_pool_size` 1947 would limit only the idle sockets the pool would hold onto, not the 1948 number of open sockets. The default has also changed, from 10 to 100. 1949 If you pass a value for ``max_pool_size`` make sure it is large enough for 1950 the expected load. (Sockets are only opened when needed, so there is no cost 1951 to having a ``max_pool_size`` larger than necessary. Err towards a larger 1952 value.) If your application accepts the default, continue to do so. 1953 1954 See :ref:`connection-pooling` for more information. 1955 1956Issues Resolved 1957............... 1958 1959See the `PyMongo 2.6 release notes in JIRA`_ for the list of resolved issues 1960in this release. 1961 1962.. _PyMongo 2.6 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=12380 1963 1964Changes in Version 2.5.2 1965------------------------ 1966 1967Version 2.5.2 fixes a NULL pointer dereference issue when decoding 1968an invalid :class:`~bson.dbref.DBRef`. 1969 1970Issues Resolved 1971............... 1972 1973See the `PyMongo 2.5.2 release notes in JIRA`_ for the list of resolved issues 1974in this release. 1975 1976.. _PyMongo 2.5.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=12581 1977 1978Changes in Version 2.5.1 1979------------------------ 1980 1981Version 2.5.1 is a minor release that fixes issues discovered after the 1982release of 2.5. Most importantly, this release addresses some race 1983conditions in replica set monitoring. 1984 1985Issues Resolved 1986............... 1987 1988See the `PyMongo 2.5.1 release notes in JIRA`_ for the list of resolved issues 1989in this release. 1990 1991.. _PyMongo 2.5.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=12484 1992 1993Changes in Version 2.5 1994---------------------- 1995 1996Version 2.5 includes changes to support new features in MongoDB 2.4. 1997 1998Important new features: 1999 2000- Support for :ref:`GSSAPI (Kerberos) authentication <gssapi>`. 2001- Support for SSL certificate validation with hostname matching. 2002- Support for delegated and role based authentication. 2003- New GEOSPHERE (2dsphere) and HASHED index constants. 2004 2005.. note:: :meth:`~pymongo.database.Database.authenticate` now raises a 2006 subclass of :class:`~pymongo.errors.PyMongoError` if authentication 2007 fails due to invalid credentials or configuration issues. 2008 2009Issues Resolved 2010............... 2011 2012See the `PyMongo 2.5 release notes in JIRA`_ for the list of resolved issues 2013in this release. 2014 2015.. _PyMongo 2.5 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=11981 2016 2017Changes in Version 2.4.2 2018------------------------ 2019 2020Version 2.4.2 is a minor release that fixes issues discovered after the 2021release of 2.4.1. Most importantly, PyMongo will no longer select a replica 2022set member for read operations that is not in primary or secondary state. 2023 2024Issues Resolved 2025............... 2026 2027See the `PyMongo 2.4.2 release notes in JIRA`_ for the list of resolved issues 2028in this release. 2029 2030.. _PyMongo 2.4.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=12299 2031 2032Changes in Version 2.4.1 2033------------------------ 2034 2035Version 2.4.1 is a minor release that fixes issues discovered after the 2036release of 2.4. Most importantly, this release fixes a regression using 2037:meth:`~pymongo.collection.Collection.aggregate`, and possibly other commands, 2038with mongos. 2039 2040Issues Resolved 2041............... 2042 2043See the `PyMongo 2.4.1 release notes in JIRA`_ for the list of resolved issues 2044in this release. 2045 2046.. _PyMongo 2.4.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=12286 2047 2048Changes in Version 2.4 2049---------------------- 2050 2051Version 2.4 includes a few important new features and a large number of bug 2052fixes. 2053 2054Important new features: 2055 2056- New :class:`~pymongo.mongo_client.MongoClient` and 2057 :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient` classes - 2058 these connection classes do acknowledged write operations (previously referred 2059 to as 'safe' writes) by default. :class:`~pymongo.connection.Connection` and 2060 :class:`~pymongo.replica_set_connection.ReplicaSetConnection` are deprecated 2061 but still support the old default fire-and-forget behavior. 2062- A new write concern API implemented as a 2063 :attr:`~pymongo.collection.Collection.write_concern` attribute on the connection, 2064 :class:`~pymongo.database.Database`, or :class:`~pymongo.collection.Collection` 2065 classes. 2066- :class:`~pymongo.mongo_client.MongoClient` (and :class:`~pymongo.connection.Connection`) 2067 now support Unix Domain Sockets. 2068- :class:`~pymongo.cursor.Cursor` can be copied with functions from the :mod:`copy` 2069 module. 2070- The :meth:`~pymongo.database.Database.set_profiling_level` method now supports 2071 a `slow_ms` option. 2072- The replica set monitor task (used by 2073 :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient` and 2074 :class:`~pymongo.replica_set_connection.ReplicaSetConnection`) is a daemon thread 2075 once again, meaning you won't have to call 2076 :meth:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient.close` before 2077 exiting the python interactive shell. 2078 2079.. warning:: 2080 2081 The constructors for :class:`~pymongo.mongo_client.MongoClient`, 2082 :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`, 2083 :class:`~pymongo.connection.Connection`, and 2084 :class:`~pymongo.replica_set_connection.ReplicaSetConnection` now raise 2085 :exc:`~pymongo.errors.ConnectionFailure` instead of its subclass 2086 :exc:`~pymongo.errors.AutoReconnect` if the server is unavailable. Applications 2087 that expect to catch :exc:`~pymongo.errors.AutoReconnect` should now catch 2088 :exc:`~pymongo.errors.ConnectionFailure` while creating a new connection. 2089 2090Issues Resolved 2091............... 2092 2093See the `PyMongo 2.4 release notes in JIRA`_ for the list of resolved issues 2094in this release. 2095 2096.. _PyMongo 2.4 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=11485 2097 2098Changes in Version 2.3 2099---------------------- 2100 2101Version 2.3 adds support for new features and behavior changes in MongoDB 21022.2. 2103 2104Important New Features: 2105 2106- Support for expanded read preferences including directing reads to tagged 2107 servers - See :ref:`secondary-reads` for more information. 2108- Support for mongos failover. 2109- A new :meth:`~pymongo.collection.Collection.aggregate` method to support 2110 MongoDB's new `aggregation framework 2111 <http://docs.mongodb.org/manual/applications/aggregation/>`_. 2112- Support for legacy Java and C# byte order when encoding and decoding UUIDs. 2113- Support for connecting directly to an arbiter. 2114 2115.. warning:: 2116 2117 Starting with MongoDB 2.2 the getLastError command requires authentication 2118 when the server's `authentication features 2119 <http://www.mongodb.org/display/DOCS/Security+and+Authentication>`_ are enabled. 2120 Changes to PyMongo were required to support this behavior change. Users of 2121 authentication must upgrade to PyMongo 2.3 (or newer) for "safe" write operations 2122 to function correctly. 2123 2124Issues Resolved 2125............... 2126 2127See the `PyMongo 2.3 release notes in JIRA`_ for the list of resolved issues 2128in this release. 2129 2130.. _PyMongo 2.3 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=11146 2131 2132Changes in Version 2.2.1 2133------------------------ 2134 2135Version 2.2.1 is a minor release that fixes issues discovered after the 2136release of 2.2. Most importantly, this release fixes an incompatibility 2137with mod_wsgi 2.x that could cause connections to leak. Users of mod_wsgi 21382.x are strongly encouraged to upgrade from PyMongo 2.2. 2139 2140Issues Resolved 2141............... 2142 2143See the `PyMongo 2.2.1 release notes in JIRA`_ for the list of resolved issues 2144in this release. 2145 2146.. _PyMongo 2.2.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=11185 2147 2148Changes in Version 2.2 2149---------------------- 2150 2151Version 2.2 adds a few more frequently requested features and fixes a 2152number of bugs. 2153 2154Special thanks go to Alex Grönholm for his contributions to Python 3 2155support and maintaining the original pymongo3 port. Christoph Simon, 2156Wouter Bolsterlee, Mike O'Brien, and Chris Tompkinson also contributed 2157to this release. 2158 2159Important New Features: 2160 2161- Support for Python 3 - 2162 See the :doc:`python3` for more information. 2163- Support for Gevent - 2164 See :doc:`examples/gevent` for more information. 2165- Improved connection pooling. 2166 See `PYTHON-287 <https://jira.mongodb.org/browse/PYTHON-287>`_. 2167 2168.. warning:: 2169 2170 A number of methods and method parameters that were deprecated in 2171 PyMongo 1.9 or older versions have been removed in this release. 2172 The full list of changes can be found in the following JIRA ticket: 2173 2174 https://jira.mongodb.org/browse/PYTHON-305 2175 2176 BSON module aliases from the pymongo package that were deprecated in 2177 PyMongo 1.9 have also been removed in this release. See the following 2178 JIRA ticket for details: 2179 2180 https://jira.mongodb.org/browse/PYTHON-304 2181 2182 As a result of this cleanup some minor code changes may be required 2183 to use this release. 2184 2185Issues Resolved 2186............... 2187 2188See the `PyMongo 2.2 release notes in JIRA`_ for the list of resolved issues 2189in this release. 2190 2191.. _PyMongo 2.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=10584 2192 2193Changes in Version 2.1.1 2194------------------------ 2195 2196Version 2.1.1 is a minor release that fixes a few issues 2197discovered after the release of 2.1. You can now use 2198:class:`~pymongo.replica_set_connection.ReplicaSetConnection` 2199to run inline map reduce commands on secondaries. See 2200:meth:`~pymongo.collection.Collection.inline_map_reduce` for details. 2201 2202Special thanks go to Samuel Clay and Ross Lawley for their contributions 2203to this release. 2204 2205Issues Resolved 2206............... 2207 2208See the `PyMongo 2.1.1 release notes in JIRA`_ for the list of resolved issues 2209in this release. 2210 2211.. _PyMongo 2.1.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?version=11081&styleName=Html&projectId=10004 2212 2213Changes in Version 2.1 2214---------------------- 2215 2216Version 2.1 adds a few frequently requested features and includes the usual 2217round of bug fixes and improvements. 2218 2219Special thanks go to Alexey Borzenkov, Dan Crosta, Kostya Rybnikov, 2220Flavio Percoco Premoli, Jonas Haag, and Jesse Davis for their contributions 2221to this release. 2222 2223Important New Features: 2224 2225- ReplicaSetConnection - 2226 :class:`~pymongo.replica_set_connection.ReplicaSetConnection` 2227 can be used to distribute reads to secondaries in a replica set. It supports 2228 automatic failover handling and periodically checks the state of the 2229 replica set to handle issues like primary stepdown or secondaries 2230 being removed for backup operations. Read preferences are defined through 2231 :class:`~pymongo.read_preferences.ReadPreference`. 2232- PyMongo supports the new BSON binary subtype 4 for UUIDs. The default 2233 subtype to use can be set through 2234 :attr:`~pymongo.collection.Collection.uuid_subtype` 2235 The current default remains :attr:`~bson.binary.OLD_UUID_SUBTYPE` but will 2236 be changed to :attr:`~bson.binary.UUID_SUBTYPE` in a future release. 2237- The getLastError option 'w' can be set to a string, allowing for options 2238 like "majority" available in newer version of MongoDB. 2239- Added support for the MongoDB URI options socketTimeoutMS and connectTimeoutMS. 2240- Added support for the ContinueOnError insert flag. 2241- Added basic SSL support. 2242- Added basic support for Jython. 2243- Secondaries can be used for :meth:`~pymongo.cursor.Cursor.count`, 2244 :meth:`~pymongo.cursor.Cursor.distinct`, :meth:`~pymongo.collection.Collection.group`, 2245 and querying :class:`~gridfs.GridFS`. 2246- Added document_class and tz_aware options to 2247 :class:`~pymongo.master_slave_connection.MasterSlaveConnection` 2248 2249Issues Resolved 2250............... 2251 2252See the `PyMongo 2.1 release notes in JIRA`_ for the list of resolved issues in this release. 2253 2254.. _PyMongo 2.1 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=10583 2255 2256Changes in Version 2.0.1 2257------------------------ 2258 2259Version 2.0.1 fixes a regression in :class:`~gridfs.grid_file.GridIn` when 2260writing pre-chunked strings. Thanks go to Alexey Borzenkov for reporting the 2261issue and submitting a patch. 2262 2263Issues Resolved 2264............... 2265 2266- `PYTHON-271 <https://jira.mongodb.org/browse/PYTHON-271>`_: 2267 Regression in GridFS leads to serious loss of data. 2268 2269Changes in Version 2.0 2270---------------------- 2271 2272Version 2.0 adds a large number of features and fixes a number of issues. 2273 2274Special thanks go to James Murty, Abhay Vardhan, David Pisoni, Ryan Smith-Roberts, 2275Andrew Pendleton, Mher Movsisyan, Reed O'Brien, Michael Schurter, Josip Delic 2276and Jonas Haag for their contributions to this release. 2277 2278Important New Features: 2279 2280- PyMongo now performs automatic per-socket database authentication. You no 2281 longer have to re-authenticate for each new thread or after a replica set 2282 failover. Authentication credentials are cached by the driver until the 2283 application calls :meth:`~pymongo.database.Database.logout`. 2284- slave_okay can be set independently at the connection, database, collection 2285 or query level. Each level will inherit the slave_okay setting from the 2286 previous level and each level can override the previous level's setting. 2287- safe and getLastError options (e.g. w, wtimeout, etc.) can be set 2288 independently at the connection, database, collection or query level. Each 2289 level will inherit settings from the previous level and each level can 2290 override the previous level's setting. 2291- PyMongo now supports the `await_data` and `partial` cursor flags. If the 2292 `await_data` flag is set on a `tailable` cursor the server will block for 2293 some extra time waiting for more data to return. The `partial` flag tells 2294 a mongos to return partial data for a query if not all shards are available. 2295- :meth:`~pymongo.collection.Collection.map_reduce` will accept a `dict` or 2296 instance of :class:`~bson.son.SON` as the `out` parameter. 2297- The URI parser has been moved into its own module and can be used directly 2298 by application code. 2299- AutoReconnect exception now provides information about the error that 2300 actually occured instead of a generic failure message. 2301- A number of new helper methods have been added with options for setting and 2302 unsetting cursor flags, re-indexing a collection, fsync and locking a server, 2303 and getting the server's current operations. 2304 2305API changes: 2306 2307- If only one host:port pair is specified :class:`~pymongo.connection.Connection` 2308 will make a direct connection to only that host. Please note that `slave_okay` 2309 must be `True` in order to query from a secondary. 2310- If more than one host:port pair is specified or the `replicaset` option is 2311 used PyMongo will treat the specified host:port pair(s) as a seed list and 2312 connect using replica set behavior. 2313 2314.. warning:: 2315 2316 The default subtype for :class:`~bson.binary.Binary` has changed 2317 from :const:`~bson.binary.OLD_BINARY_SUBTYPE` (2) to 2318 :const:`~bson.binary.BINARY_SUBTYPE` (0). 2319 2320Issues Resolved 2321............... 2322 2323See the `PyMongo 2.0 release notes in JIRA`_ for the list of resolved issues in this release. 2324 2325.. _PyMongo 2.0 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=10274 2326 2327Changes in Version 1.11 2328----------------------- 2329 2330Version 1.11 adds a few new features and fixes a few more bugs. 2331 2332New Features: 2333 2334- Basic IPv6 support: pymongo prefers IPv4 but will try IPv6. You can 2335 also specify an IPv6 address literal in the `host` parameter or a 2336 MongoDB URI provided it is enclosed in '[' and ']'. 2337- max_pool_size option: previously pymongo had a hard coded pool size 2338 of 10 connections. With this change you can specify a different pool 2339 size as a parameter to :class:`~pymongo.connection.Connection` 2340 (max_pool_size=<integer>) or in the MongoDB URI (maxPoolSize=<integer>). 2341- Find by metadata in GridFS: You can know specify query fields as 2342 keyword parameters for :meth:`~gridfs.GridFS.get_version` and 2343 :meth:`~gridfs.GridFS.get_last_version`. 2344- Per-query slave_okay option: slave_okay=True is now a valid keyword 2345 argument for :meth:`~pymongo.collection.Collection.find` and 2346 :meth:`~pymongo.collection.Collection.find_one`. 2347 2348API changes: 2349 2350- :meth:`~pymongo.database.Database.validate_collection` now returns a 2351 dict instead of a string. This change was required to deal with an 2352 API change on the server. This method also now takes the optional 2353 `scandata` and `full` parameters. See the documentation for more 2354 details. 2355 2356.. warning:: The `pool_size`, `auto_start_request`, and `timeout` parameters 2357 for :class:`~pymongo.connection.Connection` have been completely 2358 removed in this release. They were deprecated in pymongo-1.4 and 2359 have had no effect since then. Please make sure that your code 2360 doesn't currently pass these parameters when creating a 2361 Connection instance. 2362 2363Issues resolved 2364............... 2365 2366- `PYTHON-241 <https://jira.mongodb.org/browse/PYTHON-241>`_: 2367 Support setting slaveok at the cursor level. 2368- `PYTHON-240 <https://jira.mongodb.org/browse/PYTHON-240>`_: 2369 Queries can sometimes permanently fail after a replica set fail over. 2370- `PYTHON-238 <https://jira.mongodb.org/browse/PYTHON-238>`_: 2371 error after few million requests 2372- `PYTHON-237 <https://jira.mongodb.org/browse/PYTHON-237>`_: 2373 Basic IPv6 support. 2374- `PYTHON-236 <https://jira.mongodb.org/browse/PYTHON-236>`_: 2375 Restore option to specify pool size in Connection. 2376- `PYTHON-212 <https://jira.mongodb.org/browse/PYTHON-212>`_: 2377 pymongo does not recover after stale config 2378- `PYTHON-138 <https://jira.mongodb.org/browse/PYTHON-138>`_: 2379 Find method for GridFS 2380 2381Changes in Version 1.10.1 2382------------------------- 2383 2384Version 1.10.1 is primarily a bugfix release. It fixes a regression in 2385version 1.10 that broke pickling of ObjectIds. A number of other bugs 2386have been fixed as well. 2387 2388There are two behavior changes to be aware of: 2389 2390- If a read slave raises :class:`~pymongo.errors.AutoReconnect` 2391 :class:`~pymongo.master_slave_connection.MasterSlaveConnection` will now 2392 retry the query on each slave until it is successful or all slaves have 2393 raised :class:`~pymongo.errors.AutoReconnect`. Any other exception will 2394 immediately be raised. The order that the slaves are tried is random. 2395 Previously the read would be sent to one randomly chosen slave and 2396 :class:`~pymongo.errors.AutoReconnect` was immediately raised in case 2397 of a connection failure. 2398- A Python `long` is now always BSON encoded as an int64. Previously the 2399 encoding was based only on the value of the field and a `long` with a 2400 value less than `2147483648` or greater than `-2147483649` would always 2401 be BSON encoded as an int32. 2402 2403Issues resolved 2404............... 2405 2406- `PYTHON-234 <https://jira.mongodb.org/browse/PYTHON-234>`_: 2407 Fix setup.py to raise exception if any when building extensions 2408- `PYTHON-233 <https://jira.mongodb.org/browse/PYTHON-233>`_: 2409 Add information to build and test with extensions on windows 2410- `PYTHON-232 <https://jira.mongodb.org/browse/PYTHON-232>`_: 2411 Traceback when hashing a DBRef instance 2412- `PYTHON-231 <https://jira.mongodb.org/browse/PYTHON-231>`_: 2413 Traceback when pickling a DBRef instance 2414- `PYTHON-230 <https://jira.mongodb.org/browse/PYTHON-230>`_: 2415 Pickled ObjectIds are not compatible between pymongo 1.9 and 1.10 2416- `PYTHON-228 <https://jira.mongodb.org/browse/PYTHON-228>`_: 2417 Cannot pickle bson.ObjectId 2418- `PYTHON-227 <https://jira.mongodb.org/browse/PYTHON-227>`_: 2419 Traceback when calling find() on system.js 2420- `PYTHON-216 <https://jira.mongodb.org/browse/PYTHON-216>`_: 2421 MasterSlaveConnection is missing disconnect() method 2422- `PYTHON-186 <https://jira.mongodb.org/browse/PYTHON-186>`_: 2423 When storing integers, type is selected according to value instead of type 2424- `PYTHON-173 <https://jira.mongodb.org/browse/PYTHON-173>`_: 2425 as_class option is not propogated by Cursor.clone 2426- `PYTHON-113 <https://jira.mongodb.org/browse/PYTHON-113>`_: 2427 Redunducy in MasterSlaveConnection 2428 2429Changes in Version 1.10 2430----------------------- 2431 2432Version 1.10 includes changes to support new features in MongoDB 1.8.x. 2433Highlights include a modified map/reduce API including an inline map/reduce 2434helper method, a new find_and_modify helper, and the ability to query the 2435server for the maximum BSON document size it supports. 2436 2437- added :meth:`~pymongo.collection.Collection.find_and_modify`. 2438- added :meth:`~pymongo.collection.Collection.inline_map_reduce`. 2439- changed :meth:`~pymongo.collection.Collection.map_reduce`. 2440 2441.. warning:: MongoDB versions greater than 1.7.4 no longer generate temporary 2442 collections for map/reduce results. An output collection name must be 2443 provided and the output will replace any existing output collection with 2444 the same name. :meth:`~pymongo.collection.Collection.map_reduce` now 2445 requires the `out` parameter. 2446 2447Issues resolved 2448............... 2449 2450- PYTHON-225: :class:`~pymongo.objectid.ObjectId` class definition should use __slots__. 2451- PYTHON-223: Documentation fix. 2452- PYTHON-220: Documentation fix. 2453- PYTHON-219: KeyError in :meth:`~pymongo.collection.Collection.find_and_modify` 2454- PYTHON-213: Query server for maximum BSON document size. 2455- PYTHON-208: Fix :class:`~pymongo.connection.Connection` __repr__. 2456- PYTHON-207: Changes to Map/Reduce API. 2457- PYTHON-205: Accept slaveOk in the URI to match the URI docs. 2458- PYTHON-203: When slave_okay=True and we only specify one host don't autodetect other set members. 2459- PYTHON-194: Show size when whining about a document being too large. 2460- PYTHON-184: Raise :class:`~pymongo.errors.DuplicateKeyError` for duplicate keys in capped collections. 2461- PYTHON-178: Don't segfault when trying to encode a recursive data structure. 2462- PYTHON-177: Don't segfault when decoding dicts with broken iterators. 2463- PYTHON-172: Fix a typo. 2464- PYTHON-170: Add :meth:`~pymongo.collection.Collection.find_and_modify`. 2465- PYTHON-169: Support deepcopy of DBRef. 2466- PYTHON-167: Duplicate of PYTHON-166. 2467- PYTHON-166: Fixes a concurrency issue. 2468- PYTHON-158: Add code and err string to `db assertion` messages. 2469 2470Changes in Version 1.9 2471---------------------- 2472 2473Version 1.9 adds a new package to the PyMongo distribution, 2474:mod:`bson`. :mod:`bson` contains all of the `BSON 2475<http://bsonspec.org>`_ encoding and decoding logic, and the BSON 2476types that were formerly in the :mod:`pymongo` package. The following 2477modules have been renamed: 2478 2479 - :mod:`pymongo.bson` -> :mod:`bson` 2480 - :mod:`pymongo._cbson` -> :mod:`bson._cbson` and 2481 :mod:`pymongo._cmessage` 2482 - :mod:`pymongo.binary` -> :mod:`bson.binary` 2483 - :mod:`pymongo.code` -> :mod:`bson.code` 2484 - :mod:`pymongo.dbref` -> :mod:`bson.dbref` 2485 - :mod:`pymongo.json_util` -> :mod:`bson.json_util` 2486 - :mod:`pymongo.max_key` -> :mod:`bson.max_key` 2487 - :mod:`pymongo.min_key` -> :mod:`bson.min_key` 2488 - :mod:`pymongo.objectid` -> :mod:`bson.objectid` 2489 - :mod:`pymongo.son` -> :mod:`bson.son` 2490 - :mod:`pymongo.timestamp` -> :mod:`bson.timestamp` 2491 - :mod:`pymongo.tz_util` -> :mod:`bson.tz_util` 2492 2493In addition, the following exception classes have been renamed: 2494 2495 - :class:`pymongo.errors.InvalidBSON` -> 2496 :class:`bson.errors.InvalidBSON` 2497 - :class:`pymongo.errors.InvalidStringData` -> 2498 :class:`bson.errors.InvalidStringData` 2499 - :class:`pymongo.errors.InvalidDocument` -> 2500 :class:`bson.errors.InvalidDocument` 2501 - :class:`pymongo.errors.InvalidId` -> 2502 :class:`bson.errors.InvalidId` 2503 2504The above exceptions now inherit from :class:`bson.errors.BSONError` 2505rather than :class:`pymongo.errors.PyMongoError`. 2506 2507.. note:: All of the renamed modules and exceptions above have aliases 2508 created with the old names, so these changes should not break 2509 existing code. The old names will eventually be deprecated and then 2510 removed, so users should begin migrating towards the new names now. 2511 2512.. warning:: 2513 2514 The change to the exception hierarchy mentioned above is 2515 possibly breaking. If your code is catching 2516 :class:`~pymongo.errors.PyMongoError`, then the exceptions raised 2517 by :mod:`bson` will not be caught, even though they would have been 2518 caught previously. Before upgrading, it is recommended that users 2519 check for any cases like this. 2520 2521- the C extension now shares buffer.c/h with the Ruby driver 2522- :mod:`bson` no longer raises :class:`~pymongo.errors.InvalidName`, 2523 all occurrences have been replaced with 2524 :class:`~bson.errors.InvalidDocument`. 2525- renamed :meth:`bson._to_dicts` to :meth:`~bson.decode_all`. 2526- renamed :meth:`~bson.BSON.from_dict` to :meth:`~bson.BSON.encode` 2527 and :meth:`~bson.BSON.to_dict` to :meth:`~bson.BSON.decode`. 2528- added :meth:`~pymongo.cursor.Cursor.batch_size`. 2529- allow updating (some) file metadata after a 2530 :class:`~gridfs.grid_file.GridIn` instance has been closed. 2531- performance improvements for reading from GridFS. 2532- special cased slice with the same start and stop to return an empty 2533 cursor. 2534- allow writing :class:`unicode` to GridFS if an :attr:`encoding` 2535 attribute has been specified for the file. 2536- added :meth:`gridfs.GridFS.get_version`. 2537- scope variables for :class:`~bson.code.Code` can now be specified as 2538 keyword arguments. 2539- added :meth:`~gridfs.grid_file.GridOut.readline` to 2540 :class:`~gridfs.grid_file.GridOut`. 2541- make a best effort to transparently auto-reconnect if a 2542 :class:`~pymongo.connection.Connection` has been idle for a while. 2543- added :meth:`~pymongo.database.SystemJS.list` to 2544 :class:`~pymongo.database.SystemJS`. 2545- added `file_document` argument to :meth:`~gridfs.grid_file.GridOut` 2546 to allow initializing from an existing file document. 2547- raise :class:`~pymongo.errors.TimeoutError` even if the 2548 ``getLastError`` command was run manually and not through "safe" 2549 mode. 2550- added :class:`uuid` support to :mod:`~bson.json_util`. 2551 2552Changes in Version 1.8.1 2553------------------------ 2554 2555- fixed a typo in the C extension that could cause safe-mode 2556 operations to report a failure (:class:`SystemError`) even when none 2557 occurred. 2558- added a :meth:`__ne__` implementation to any class where we define 2559 :meth:`__eq__`. 2560 2561Changes in Version 1.8 2562---------------------- 2563 2564Version 1.8 adds support for connecting to replica sets, specifying 2565per-operation values for `w` and `wtimeout`, and decoding to 2566timezone-aware datetimes. 2567 2568- fixed a reference leak in the C extension when decoding a 2569 :class:`~bson.dbref.DBRef`. 2570- added support for `w`, `wtimeout`, and `fsync` (and any other 2571 options for `getLastError`) to "safe mode" operations. 2572- added :attr:`~pymongo.connection.Connection.nodes` property. 2573- added a maximum pool size of 10 sockets. 2574- added support for replica sets. 2575- DEPRECATED :meth:`~pymongo.connection.Connection.from_uri` and 2576 :meth:`~pymongo.connection.Connection.paired`, both are supplanted 2577 by extended functionality in :meth:`~pymongo.connection.Connection`. 2578- added tz aware support for datetimes in 2579 :class:`~bson.objectid.ObjectId`, 2580 :class:`~bson.timestamp.Timestamp` and :mod:`~bson.json_util` 2581 methods. 2582- added :meth:`~pymongo.collection.Collection.drop` helper. 2583- reuse the socket used for finding the master when a 2584 :class:`~pymongo.connection.Connection` is first created. 2585- added support for :class:`~bson.min_key.MinKey`, 2586 :class:`~bson.max_key.MaxKey` and 2587 :class:`~bson.timestamp.Timestamp` to :mod:`~bson.json_util`. 2588- added support for decoding datetimes as aware (UTC) - it is highly 2589 recommended to enable this by setting the `tz_aware` parameter to 2590 :meth:`~pymongo.connection.Connection` to ``True``. 2591- added `network_timeout` option for individual calls to 2592 :meth:`~pymongo.collection.Collection.find` and 2593 :meth:`~pymongo.collection.Collection.find_one`. 2594- added :meth:`~gridfs.GridFS.exists` to check if a file exists in 2595 GridFS. 2596- added support for additional keys in :class:`~bson.dbref.DBRef` 2597 instances. 2598- added :attr:`~pymongo.errors.OperationFailure.code` attribute to 2599 :class:`~pymongo.errors.OperationFailure` exceptions. 2600- fixed serialization of int and float subclasses in the C extension. 2601 2602Changes in Version 1.7 2603---------------------- 2604 2605Version 1.7 is a recommended upgrade for all PyMongo users. The full 2606release notes are below, and some more in depth discussion of the 2607highlights is `here 2608<http://dirolf.com/2010/06/17/pymongo-1.7-released.html>`_. 2609 2610- no longer attempt to build the C extension on big-endian systems. 2611- added :class:`~bson.min_key.MinKey` and 2612 :class:`~bson.max_key.MaxKey`. 2613- use unsigned for :class:`~bson.timestamp.Timestamp` in BSON 2614 encoder/decoder. 2615- support ``True`` as ``"ok"`` in command responses, in addition to 2616 ``1.0`` - necessary for server versions **>= 1.5.X** 2617- BREAKING change to 2618 :meth:`~pymongo.collection.Collection.index_information` to add 2619 support for querying unique status and other index information. 2620- added :attr:`~pymongo.connection.Connection.document_class`, to 2621 specify class for returned documents. 2622- added `as_class` argument for 2623 :meth:`~pymongo.collection.Collection.find`, and in the BSON decoder. 2624- added support for creating :class:`~bson.timestamp.Timestamp` 2625 instances using a :class:`~datetime.datetime`. 2626- allow `dropTarget` argument for 2627 :class:`~pymongo.collection.Collection.rename`. 2628- handle aware :class:`~datetime.datetime` instances, by converting to 2629 UTC. 2630- added support for :class:`~pymongo.cursor.Cursor.max_scan`. 2631- raise :class:`~gridfs.errors.FileExists` exception when creating a 2632 duplicate GridFS file. 2633- use `y2038 <http://code.google.com/p/y2038/>`_ for time handling in 2634 the C extension - eliminates 2038 problems when extension is 2635 installed. 2636- added `sort` parameter to 2637 :meth:`~pymongo.collection.Collection.find` 2638- finalized deprecation of changes from versions **<= 1.4** 2639- take any non-:class:`dict` as an ``"_id"`` query for 2640 :meth:`~pymongo.collection.Collection.find_one` or 2641 :meth:`~pymongo.collection.Collection.remove` 2642- added ability to pass a :class:`dict` for `fields` argument to 2643 :meth:`~pymongo.collection.Collection.find` (supports ``"$slice"`` 2644 and field negation) 2645- simplified code to find master, since paired setups don't always have 2646 a remote 2647- fixed bug in C encoder for certain invalid types (like 2648 :class:`~pymongo.collection.Collection` instances). 2649- don't transparently map ``"filename"`` key to :attr:`name` attribute 2650 for GridFS. 2651 2652Changes in Version 1.6 2653---------------------- 2654 2655The biggest change in version 1.6 is a complete re-implementation of 2656:mod:`gridfs` with a lot of improvements over the old 2657implementation. There are many details and examples of using the new 2658API in `this blog post 2659<http://dirolf.com/2010/03/29/new-gridfs-implementation-for-pymongo.html>`_. The 2660old API has been removed in this version, so existing code will need 2661to be modified before upgrading to 1.6. 2662 2663- fixed issue where connection pool was being shared across 2664 :class:`~pymongo.connection.Connection` instances. 2665- more improvements to Python code caching in C extension - should 2666 improve behavior on mod_wsgi. 2667- added :meth:`~bson.objectid.ObjectId.from_datetime`. 2668- complete rewrite of :mod:`gridfs` support. 2669- improvements to the :meth:`~pymongo.database.Database.command` API. 2670- fixed :meth:`~pymongo.collection.Collection.drop_indexes` behavior 2671 on non-existent collections. 2672- disallow empty bulk inserts. 2673 2674Changes in Version 1.5.2 2675------------------------ 2676- fixed response handling to ignore unknown response flags in queries. 2677- handle server versions containing '-pre-'. 2678 2679Changes in Version 1.5.1 2680------------------------ 2681- added :data:`~gridfs.grid_file.GridFile._id` property for 2682 :class:`~gridfs.grid_file.GridFile` instances. 2683- fix for making a :class:`~pymongo.connection.Connection` (with 2684 `slave_okay` set) directly to a slave in a replica pair. 2685- accept kwargs for 2686 :meth:`~pymongo.collection.Collection.create_index` and 2687 :meth:`~pymongo.collection.Collection.ensure_index` to support all 2688 indexing options. 2689- add :data:`pymongo.GEO2D` and support for geo indexing. 2690- improvements to Python code caching in C extension - should improve 2691 behavior on mod_wsgi. 2692 2693Changes in Version 1.5 2694---------------------- 2695- added subtype constants to :mod:`~bson.binary` module. 2696- DEPRECATED `options` argument to 2697 :meth:`~pymongo.collection.Collection` and 2698 :meth:`~pymongo.database.Database.create_collection` in favor of 2699 kwargs. 2700- added :meth:`~pymongo.has_c` to check for C extension. 2701- added :meth:`~pymongo.connection.Connection.copy_database`. 2702- added :data:`~pymongo.cursor.Cursor.alive` to tell when a cursor 2703 might have more data to return (useful for tailable cursors). 2704- added :class:`~bson.timestamp.Timestamp` to better support 2705 dealing with internal MongoDB timestamps. 2706- added `name` argument for 2707 :meth:`~pymongo.collection.Collection.create_index` and 2708 :meth:`~pymongo.collection.Collection.ensure_index`. 2709- fixed connection pooling w/ fork 2710- :meth:`~pymongo.connection.Connection.paired` takes all kwargs that 2711 are allowed for :meth:`~pymongo.connection.Connection`. 2712- :meth:`~pymongo.collection.Collection.insert` returns list for bulk 2713 inserts of size one. 2714- fixed handling of :class:`datetime.datetime` instances in 2715 :mod:`~bson.json_util`. 2716- added :meth:`~pymongo.connection.Connection.from_uri` to support 2717 MongoDB connection uri scheme. 2718- fixed chunk number calculation when unaligned in :mod:`gridfs`. 2719- :meth:`~pymongo.database.Database.command` takes a string for simple 2720 commands. 2721- added :data:`~pymongo.database.Database.system_js` helper for 2722 dealing with server-side JS. 2723- don't wrap queries containing ``"$query"`` (support manual use of 2724 ``"$min"``, etc.). 2725- added :class:`~gridfs.errors.GridFSError` as base class for 2726 :mod:`gridfs` exceptions. 2727 2728Changes in Version 1.4 2729---------------------- 2730 2731Perhaps the most important change in version 1.4 is that we have 2732decided to **no longer support Python 2.3**. The most immediate reason 2733for this is to allow some improvements to connection pooling. This 2734will also allow us to use some new (as in Python 2.4 ;) idioms and 2735will help begin the path towards supporting Python 3.0. If you need to 2736use Python 2.3 you should consider using version 1.3 of this driver, 2737although that will no longer be actively supported. 2738 2739Other changes: 2740 2741- move ``"_id"`` to front only for top-level documents (fixes some 2742 corner cases). 2743- :meth:`~pymongo.collection.Collection.update` and 2744 :meth:`~pymongo.collection.Collection.remove` return the entire 2745 response to the *lastError* command when safe is ``True``. 2746- completed removal of things that were deprecated in version 1.2 or 2747 earlier. 2748- enforce that collection names do not contain the NULL byte. 2749- fix to allow using UTF-8 collection names with the C extension. 2750- added :class:`~pymongo.errors.PyMongoError` as base exception class 2751 for all :mod:`~pymongo.errors`. this changes the exception hierarchy 2752 somewhat, and is a BREAKING change if you depend on 2753 :class:`~pymongo.errors.ConnectionFailure` being a :class:`IOError` 2754 or :class:`~bson.errors.InvalidBSON` being a :class:`ValueError`, 2755 for example. 2756- added :class:`~pymongo.errors.DuplicateKeyError` for calls to 2757 :meth:`~pymongo.collection.Collection.insert` or 2758 :meth:`~pymongo.collection.Collection.update` with `safe` set to 2759 ``True``. 2760- removed :mod:`~pymongo.thread_util`. 2761- added :meth:`~pymongo.database.Database.add_user` and 2762 :meth:`~pymongo.database.Database.remove_user` helpers. 2763- fix for :meth:`~pymongo.database.Database.authenticate` when using 2764 non-UTF-8 names or passwords. 2765- minor fixes for 2766 :class:`~pymongo.master_slave_connection.MasterSlaveConnection`. 2767- clean up all cases where :class:`~pymongo.errors.ConnectionFailure` 2768 is raised. 2769- simplification of connection pooling - makes driver ~2x faster for 2770 simple benchmarks. see :ref:`connection-pooling` for more information. 2771- DEPRECATED `pool_size`, `auto_start_request` and `timeout` 2772 parameters to :class:`~pymongo.connection.Connection`. DEPRECATED 2773 :meth:`~pymongo.connection.Connection.start_request`. 2774- use :meth:`socket.sendall`. 2775- removed :meth:`~bson.son.SON.from_xml` as it was only being used 2776 for some internal testing - also eliminates dependency on 2777 :mod:`elementtree`. 2778- implementation of :meth:`~pymongo.message.update` in C. 2779- deprecate :meth:`~pymongo.database.Database._command` in favor of 2780 :meth:`~pymongo.database.Database.command`. 2781- send all commands without wrapping as ``{"query": ...}``. 2782- support string as `key` argument to 2783 :meth:`~pymongo.collection.Collection.group` (keyf) and run all 2784 groups as commands. 2785- support for equality testing for :class:`~bson.code.Code` 2786 instances. 2787- allow the NULL byte in strings and disallow it in key names or regex 2788 patterns 2789 2790Changes in Version 1.3 2791---------------------- 2792- DEPRECATED running :meth:`~pymongo.collection.Collection.group` as 2793 :meth:`~pymongo.database.Database.eval`, also changed default for 2794 :meth:`~pymongo.collection.Collection.group` to running as a command 2795- remove :meth:`pymongo.cursor.Cursor.__len__`, which was deprecated 2796 in 1.1.1 - needed to do this aggressively due to it's presence 2797 breaking **Django** template *for* loops 2798- DEPRECATED :meth:`~pymongo.connection.Connection.host`, 2799 :meth:`~pymongo.connection.Connection.port`, 2800 :meth:`~pymongo.database.Database.connection`, 2801 :meth:`~pymongo.database.Database.name`, 2802 :meth:`~pymongo.collection.Collection.database`, 2803 :meth:`~pymongo.collection.Collection.name` and 2804 :meth:`~pymongo.collection.Collection.full_name` in favor of 2805 :attr:`~pymongo.connection.Connection.host`, 2806 :attr:`~pymongo.connection.Connection.port`, 2807 :attr:`~pymongo.database.Database.connection`, 2808 :attr:`~pymongo.database.Database.name`, 2809 :attr:`~pymongo.collection.Collection.database`, 2810 :attr:`~pymongo.collection.Collection.name` and 2811 :attr:`~pymongo.collection.Collection.full_name`, respectively. The 2812 deprecation schedule for this change will probably be faster than 2813 usual, as it carries some performance implications. 2814- added :meth:`~pymongo.connection.Connection.disconnect` 2815 2816Changes in Version 1.2.1 2817------------------------ 2818- added :doc:`changelog` to docs 2819- added ``setup.py doc --test`` to run doctests for tutorial, examples 2820- moved most examples to Sphinx docs (and remove from *examples/* 2821 directory) 2822- raise :class:`~bson.errors.InvalidId` instead of 2823 :class:`TypeError` when passing a 24 character string to 2824 :class:`~bson.objectid.ObjectId` that contains non-hexadecimal 2825 characters 2826- allow :class:`unicode` instances for :class:`~bson.objectid.ObjectId` init 2827 2828Changes in Version 1.2 2829---------------------- 2830- `spec` parameter for :meth:`~pymongo.collection.Collection.remove` is 2831 now optional to allow for deleting all documents in a 2832 :class:`~pymongo.collection.Collection` 2833- always wrap queries with ``{query: ...}`` even when no special options - 2834 get around some issues with queries on fields named ``query`` 2835- enforce 4MB document limit on the client side 2836- added :meth:`~pymongo.collection.Collection.map_reduce` helper - see 2837 :doc:`example <examples/aggregation>` 2838- added :meth:`~pymongo.cursor.Cursor.distinct` method on 2839 :class:`~pymongo.cursor.Cursor` instances to allow distinct with 2840 queries 2841- fix for :meth:`~pymongo.cursor.Cursor.__getitem__` after 2842 :meth:`~pymongo.cursor.Cursor.skip` 2843- allow any UTF-8 string in :class:`~bson.BSON` encoder, not 2844 just ASCII subset 2845- added :attr:`~bson.objectid.ObjectId.generation_time` 2846- removed support for legacy :class:`~bson.objectid.ObjectId` 2847 format - pretty sure this was never used, and is just confusing 2848- DEPRECATED :meth:`~bson.objectid.ObjectId.url_encode` and 2849 :meth:`~bson.objectid.ObjectId.url_decode` in favor of :meth:`str` 2850 and :meth:`~bson.objectid.ObjectId`, respectively 2851- allow *oplog.$main* as a valid collection name 2852- some minor fixes for installation process 2853- added support for datetime and regex in :mod:`~bson.json_util` 2854 2855Changes in Version 1.1.2 2856------------------------ 2857- improvements to :meth:`~pymongo.collection.Collection.insert` speed 2858 (using C for insert message creation) 2859- use random number for request_id 2860- fix some race conditions with :class:`~pymongo.errors.AutoReconnect` 2861 2862Changes in Version 1.1.1 2863------------------------ 2864- added `multi` parameter for 2865 :meth:`~pymongo.collection.Collection.update` 2866- fix unicode regex patterns with C extension 2867- added :meth:`~pymongo.collection.Collection.distinct` 2868- added `database` support for :class:`~bson.dbref.DBRef` 2869- added :mod:`~bson.json_util` with helpers for encoding / decoding 2870 special types to JSON 2871- DEPRECATED :meth:`pymongo.cursor.Cursor.__len__` in favor of 2872 :meth:`~pymongo.cursor.Cursor.count` with `with_limit_and_skip` set 2873 to ``True`` due to performance regression 2874- switch documentation to Sphinx 2875 2876Changes in Version 1.1 2877---------------------- 2878- added :meth:`__hash__` for :class:`~bson.dbref.DBRef` and 2879 :class:`~bson.objectid.ObjectId` 2880- bulk :meth:`~pymongo.collection.Collection.insert` works with any 2881 iterable 2882- fix :class:`~bson.objectid.ObjectId` generation when using 2883 :mod:`multiprocessing` 2884- added :attr:`~pymongo.cursor.Cursor.collection` 2885- added `network_timeout` parameter for 2886 :meth:`~pymongo.connection.Connection` 2887- DEPRECATED `slave_okay` parameter for individual queries 2888- fix for `safe` mode when multi-threaded 2889- added `safe` parameter for :meth:`~pymongo.collection.Collection.remove` 2890- added `tailable` parameter for :meth:`~pymongo.collection.Collection.find` 2891 2892Changes in Version 1.0 2893---------------------- 2894- fixes for 2895 :class:`~pymongo.master_slave_connection.MasterSlaveConnection` 2896- added `finalize` parameter for :meth:`~pymongo.collection.Collection.group` 2897- improvements to :meth:`~pymongo.collection.Collection.insert` speed 2898- improvements to :mod:`gridfs` speed 2899- added :meth:`~pymongo.cursor.Cursor.__getitem__` and 2900 :meth:`~pymongo.cursor.Cursor.__len__` for 2901 :class:`~pymongo.cursor.Cursor` instances 2902 2903Changes in Version 0.16 2904----------------------- 2905- support for encoding/decoding :class:`uuid.UUID` instances 2906- fix for :meth:`~pymongo.cursor.Cursor.explain` with limits 2907 2908Changes in Version 0.15.2 2909------------------------- 2910- documentation changes only 2911 2912Changes in Version 0.15.1 2913------------------------- 2914- various performance improvements 2915- API CHANGE no longer need to specify direction for 2916 :meth:`~pymongo.collection.Collection.create_index` and 2917 :meth:`~pymongo.collection.Collection.ensure_index` when indexing a 2918 single key 2919- support for encoding :class:`tuple` instances as :class:`list` 2920 instances 2921 2922Changes in Version 0.15 2923----------------------- 2924- fix string representation of :class:`~bson.objectid.ObjectId` 2925 instances 2926- added `timeout` parameter for 2927 :meth:`~pymongo.collection.Collection.find` 2928- allow scope for `reduce` function in 2929 :meth:`~pymongo.collection.Collection.group` 2930 2931Changes in Version 0.14.2 2932------------------------- 2933- minor bugfixes 2934 2935Changes in Version 0.14.1 2936------------------------- 2937- :meth:`~gridfs.grid_file.GridFile.seek` and 2938 :meth:`~gridfs.grid_file.GridFile.tell` for (read mode) 2939 :class:`~gridfs.grid_file.GridFile` instances 2940 2941Changes in Version 0.14 2942----------------------- 2943- support for long in :class:`~bson.BSON` 2944- added :meth:`~pymongo.collection.Collection.rename` 2945- added `snapshot` parameter for 2946 :meth:`~pymongo.collection.Collection.find` 2947 2948Changes in Version 0.13 2949----------------------- 2950- better 2951 :class:`~pymongo.master_slave_connection.MasterSlaveConnection` 2952 support 2953- API CHANGE :meth:`~pymongo.collection.Collection.insert` and 2954 :meth:`~pymongo.collection.Collection.save` both return inserted 2955 ``_id`` 2956- DEPRECATED passing an index name to 2957 :meth:`~pymongo.cursor.Cursor.hint` 2958 2959Changes in Version 0.12 2960----------------------- 2961- improved :class:`~bson.objectid.ObjectId` generation 2962- added :class:`~pymongo.errors.AutoReconnect` exception for when 2963 reconnection is possible 2964- make :mod:`gridfs` thread-safe 2965- fix for :mod:`gridfs` with non :class:`~bson.objectid.ObjectId` ``_id`` 2966 2967Changes in Version 0.11.3 2968------------------------- 2969- don't allow NULL bytes in string encoder 2970- fixes for Python 2.3 2971 2972Changes in Version 0.11.2 2973------------------------- 2974- PEP 8 2975- updates for :meth:`~pymongo.collection.Collection.group` 2976- VS build 2977 2978Changes in Version 0.11.1 2979------------------------- 2980- fix for connection pooling under Python 2.5 2981 2982Changes in Version 0.11 2983----------------------- 2984- better build failure detection 2985- driver support for selecting fields in sub-documents 2986- disallow insertion of invalid key names 2987- added `timeout` parameter for :meth:`~pymongo.connection.Connection` 2988 2989Changes in Version 0.10.3 2990------------------------- 2991- fix bug with large :meth:`~pymongo.cursor.Cursor.limit` 2992- better exception when modules get reloaded out from underneath the C 2993 extension 2994- better exception messages when calling a 2995 :class:`~pymongo.collection.Collection` or 2996 :class:`~pymongo.database.Database` instance 2997 2998Changes in Version 0.10.2 2999------------------------- 3000- support subclasses of :class:`dict` in C encoder 3001 3002Changes in Version 0.10.1 3003------------------------- 3004- alias :class:`~pymongo.connection.Connection` as 3005 :attr:`pymongo.Connection` 3006- raise an exception rather than silently overflowing in encoder 3007 3008Changes in Version 0.10 3009----------------------- 3010- added :meth:`~pymongo.collection.Collection.ensure_index` 3011 3012Changes in Version 0.9.7 3013------------------------ 3014- allow sub-collections of *$cmd* as valid 3015 :class:`~pymongo.collection.Collection` names 3016- add version as :attr:`pymongo.version` 3017- add ``--no_ext`` command line option to *setup.py* 3018 3019.. toctree:: 3020 :hidden: 3021 3022 python3 3023 examples/gevent 3024