From 1a45a0fa08b7f4619abac825ef759acb0774f9f0 Mon Sep 17 00:00:00 2001 From: Bernie Hackett Date: Fri, 16 Sep 2016 14:31:20 -0700 Subject: [PATCH] Changelog for PyMongo 3.4 --- bson/code.py | 4 +-- doc/api/pymongo/read_preferences.rst | 6 +++- doc/changelog.rst | 52 +++++++++++++++++++++++++--- pymongo/mongo_client.py | 16 +++++++-- pymongo/read_preferences.py | 26 +++++++++----- 5 files changed, 85 insertions(+), 19 deletions(-) diff --git a/bson/code.py b/bson/code.py index 1c8b30acf..1c7b754a6 100644 --- a/bson/code.py +++ b/bson/code.py @@ -42,7 +42,7 @@ class Code(str): - `**kwargs` (optional): scope variables can also be passed as keyword arguments. These are applied after `scope` and `code`. - ..versionchanged:: 3.4 + .. versionchanged:: 3.4 The default value for :attr:`scope` is ``None`` instead of ``{}``. """ @@ -82,7 +82,7 @@ class Code(str): @property def scope(self): - """Scope dictionary for this instance. + """Scope dictionary for this instance or ``None``. """ return self.__scope diff --git a/doc/api/pymongo/read_preferences.rst b/doc/api/pymongo/read_preferences.rst index 25b6e3db8..009e87d87 100644 --- a/doc/api/pymongo/read_preferences.rst +++ b/doc/api/pymongo/read_preferences.rst @@ -5,7 +5,11 @@ :synopsis: Utilities for choosing which member of a replica set to read from. .. autoclass:: pymongo.read_preferences.Primary - :inherited-members: + + .. autoattribute:: document + .. autoattribute:: mode + .. autoattribute:: name + .. autoclass:: pymongo.read_preferences.PrimaryPreferred :inherited-members: .. autoclass:: pymongo.read_preferences.Secondary diff --git a/doc/changelog.rst b/doc/changelog.rst index c99cb892d..f41534b86 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -4,17 +4,59 @@ Changelog Changes in Version 3.4 ---------------------- -Version 3.4 implements the new server features introduced in MongoDB 3.4: +Version 3.4 implements the new server features introduced in MongoDB 3.4 +and a whole lot more: Highlights include: +- Complete support for MongoDB 3.4: + + - Unicode aware string comparison using :doc:`examples/collations`. + - Support for the new :class:`~bson.decimal128.Decimal128` BSON type. + - A new maxStalenessMS read preference option. + - :meth:`~pymongo.collection.Collection.parallel_scan` supports maxTimeMS. + - :attr:`~pymongo.write_concern.WriteConcern` is automatically + applied by all helpers for commands that write to the database when + connected to MongoDB 3.4+. This change affects the following helpers: + + - :meth:`~pymongo.mongo_client.MongoClient.drop_database` + - :meth:`~pymongo.database.Database.create_collection` + - :meth:`~pymongo.database.Database.drop_collection` + - :meth:`~pymongo.collection.Collection.aggregate` (when using $out) + - :meth:`~pymongo.collection.Collection.create_indexes` + - :meth:`~pymongo.collection.Collection.create_index` + - :meth:`~pymongo.collection.Collection.drop_indexes` + - :meth:`~pymongo.collection.Collection.drop_indexes` + - :meth:`~pymongo.collection.Collection.drop_index` + - :meth:`~pymongo.collection.Collection.map_reduce` (when output is not + "inline") + - :meth:`~pymongo.collection.Collection.reindex` + - :meth:`~pymongo.collection.Collection.rename` + +- Improved support for logging server discovery and monitoring events. See + :mod:`~pymongo.monitoring` for examples. +- Support for matching iPAddress subjectAltName values for TLS certificate + verification. +- TLS compression is now explicitly disabled when possible. +- The Server Name Indication (SNI) TLS extension is used when possible. - Finer control over JSON encoding/decoding with :class:`~bson.json_util.JSONOptions`. -- Allow :class:`~bson.code.Code` objects to have a scope of ``None``, signifying - no scope. Also allow encoding Code objects with an empty scope (i.e. ``{}``). +- Allow :class:`~bson.code.Code` objects to have a scope of ``None``, + signifying no scope. Also allow encoding Code objects with an empty scope + (i.e. ``{}``). - .. warning:: Starting in PyMongo 3.4, :attr:`~bson.code.Code.scope` may return - ``None``, as the default scope is ``None`` instead of ``{}``. +.. warning:: Starting in PyMongo 3.4, :attr:`bson.code.Code.scope` may return + ``None``, as the default scope is ``None`` instead of ``{}``. + +.. note:: PyMongo 3.4+ attempts to create sockets non-inheritable when possible + (i.e. it sets the close-on-exec flag on socket file descriptors). Support + is limited to a subset of POSIX operating systems (not including Windows) and + the flag usually cannot be set in a single atomic operation. CPython 3.4+ + implements `PEP 446`_, creating all file descriptors non-inheritable by + default. Users that require this behavior are encouraged to upgrade to + CPython 3.4+. + +.. _PEP 446: https://www.python.org/dev/peps/pep-0446/ Issues Resolved ............... diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py index 2e185e0d4..41c15e6c2 100644 --- a/pymongo/mongo_client.py +++ b/pymongo/mongo_client.py @@ -203,9 +203,19 @@ class MongoClient(common.BaseObject): match this name. Implies that the hosts specified are a seed list and the driver should attempt to find all members of the set. Defaults to ``None``. - - `read_preference`: The read preference for this client. - See :class:`~pymongo.read_preferences.ReadPreference` for all - available read preference options. Defaults to ``PRIMARY``. + + | **Read Preference:** + + - `readPreference`: The replica set read preference for this client. + One of ``primary``, ``primaryPreferred``, ``secondary``, + ``secondaryPreferred``, or ``nearest``. Defaults to ``primary``. + - `readPreferenceTags`: Specifies a tag set as a comma-separated list + of colon-separated key-value pairs. For example ``dc:ny,rack:1``. + Defaults to ``None``. + - `maxStalenessMS`: (integer or float, in milliseconds) The maximum + estimated length of time a replica set secondary can fall behind + the primary in replication before it will no longer be selected for + operations. Defaults to ``None`` (no limit). | **SSL configuration:** diff --git a/pymongo/read_preferences.py b/pymongo/read_preferences.py index dc16c12ca..1be0df014 100644 --- a/pymongo/read_preferences.py +++ b/pymongo/read_preferences.py @@ -127,7 +127,9 @@ class _ServerMode(object): @property def max_staleness(self): - """This read preference's maxStalenessMS, converted to seconds.""" + """The maximum estimated length of time (in seconds) a replica set + secondary can fall behind the primary in replication before it will + no longer be selected for operations.""" return self.__max_staleness @property @@ -135,10 +137,11 @@ class _ServerMode(object): """The wire protocol version the server must support. Some read preferences impose version requirements on all servers in the - topology. E.g., maxStalenessMS requires MongoDB 3.4 / maxWireVersion 5. + topology (e.g. maxStalenessMS requires MongoDB 3.4 / maxWireVersion 5). All servers' maxWireVersion must be at least this read preference's - `min_wire_version`, or the driver raises `ConfigurationError`. + `min_wire_version`, or the driver raises + :exc:`~pymongo.errors.ConfigurationError`. """ return 5 if self.__max_staleness else 0 @@ -212,8 +215,9 @@ class PrimaryPreferred(_ServerMode): :Parameters: - `tag_sets`: The :attr:`~tag_sets` to use if the primary is not available. - - `max_staleness`: The :attr:`~max_staleness` to use if the primary is - not available. + - `max_staleness`: (integer or float, in seconds) The maximum estimated + length of time a replica set secondary can fall behind the primary in + replication before it will no longer be selected for operations. """ def __init__(self, tag_sets=None, max_staleness=None): @@ -244,7 +248,9 @@ class Secondary(_ServerMode): :Parameters: - `tag_sets`: The :attr:`~tag_sets` for this read preference. - - `max_staleness`: The :attr:`~max_staleness` for this read preference. + - `max_staleness`: (integer or float, in seconds) The maximum estimated + length of time a replica set secondary can fall behind the primary in + replication before it will no longer be selected for operations. """ def __init__(self, tag_sets=None, max_staleness=None): @@ -270,7 +276,9 @@ class SecondaryPreferred(_ServerMode): :Parameters: - `tag_sets`: The :attr:`~tag_sets` for this read preference. - - `max_staleness`: The :attr:`~max_staleness` for this read preference. + - `max_staleness`: (integer or float, in seconds) The maximum estimated + length of time a replica set secondary can fall behind the primary in + replication before it will no longer be selected for operations. """ def __init__(self, tag_sets=None, max_staleness=None): @@ -303,7 +311,9 @@ class Nearest(_ServerMode): :Parameters: - `tag_sets`: The :attr:`~tag_sets` for this read preference. - - `max_staleness`: The :attr:`~max_staleness` for this read preference. + - `max_staleness`: (integer or float, in seconds) The maximum estimated + length of time a replica set secondary can fall behind the primary in + replication before it will no longer be selected for operations. """ def __init__(self, tag_sets=None, max_staleness=None):