PYTHON-2707 Limit the use of 'master'

This commit limits the use of the word 'master'
as much as possible without breaking API or
breaking documentation links. PyMongo 4.0 will
include backward breaking API changes to do more.

Author: behackett

doc/api/pymongo/hello.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+:mod:`hello` -- A wrapper for hello command responses.
+======================================================
+
+.. automodule:: pymongo.hello
+
+   .. autoclass:: pymongo.hello.Hello(doc)
+
+      .. autoattribute:: document

doc/api/pymongo/ismaster.rst

@@ -1,7 +1,7 @@
 :orphan:
 
-:mod:`ismaster` -- A wrapper for ismaster command responses.
-============================================================
+:mod:`ismaster` -- **DEPRECATED** A wrapper for hello command responses.
+========================================================================
 
 .. automodule:: pymongo.ismaster
 

doc/changelog.rst

@@ -43,6 +43,10 @@ Deprecations
   :meth:`~pymongo.database.Database.command` helper directly.
 - Deprecated :exc:`~pymongo.errors.NotMasterError`. Users should
   use :exc:`~pymongo.errors.NotPrimaryError` instead.
+- Deprecated :class:`~pymongo.ismaster.IsMaster` and :mod:`~pymongo.ismaster`
+  which will be removed in PyMongo 4.0 and are replaced by
+  :class:`~pymongo.hello.Hello` and :mod:`~pymongo.hello` which provide the
+  same API. 
 
 .. _PYTHON-2466: https://jira.mongodb.org/browse/PYTHON-2466
 .. _PYTHON-1690: https://jira.mongodb.org/browse/PYTHON-1690

doc/migrate-to-pymongo3.rst

@@ -433,13 +433,13 @@ can be changed to this with PyMongo 2.9 or later:
   >>> from pymongo.errors import ConnectionFailure
   >>> client = MongoClient(connect=False)
   >>> try:
-  ...     result = client.admin.command("ismaster")
+  ...     result = client.admin.command("ping")
   ... except ConnectionFailure:
   ...     print("Server not available")
   >>>
 
 Any operation can be used to determine if the server is available. We choose
-the "ismaster" command here because it is cheap and does not require auth, so
+the "ping" command here because it is cheap and does not require auth, so
 it is a simple way to check whether the server is available.
 
 The max_pool_size parameter is removed
@@ -516,9 +516,10 @@ Removed features with no migration path
 MasterSlaveConnection is removed
 ................................
 
-Master slave deployments are deprecated in MongoDB. Starting with MongoDB 3.0
-a replica set can have up to 50 members and that limit is likely to be
-removed in later releases. We recommend migrating to replica sets instead.
+Master slave deployments are no longer supported by MongoDB. Starting with
+MongoDB 3.0 a replica set can have up to 50 members and that limit is likely
+to be removed in later releases. We recommend migrating to replica sets
+instead.
 
 Requests are removed
 ....................

pymongo/auth.py

@@ -624,8 +624,8 @@ def from_credentials(creds):
     def speculate_command(self):
         raise NotImplementedError
 
-    def parse_response(self, ismaster):
-        self.speculative_authenticate = ismaster.speculative_authenticate
+    def parse_response(self, hello):
+        self.speculative_authenticate = hello.speculative_authenticate
 
     def speculate_succeeded(self):
         return bool(self.speculative_authenticate)

pymongo/common.py

@@ -60,7 +60,7 @@
 MIN_SUPPORTED_WIRE_VERSION = 2
 MAX_SUPPORTED_WIRE_VERSION = 13
 
-# Frequency to call ismaster on servers, in seconds.
+# Frequency to call hello on servers, in seconds.
 HEARTBEAT_FREQUENCY = 10
 
 # Frequency to process kill-cursors, in seconds. See MongoClient.close_cursor.
@@ -75,7 +75,7 @@
 # longest it is willing to wait for a new primary to be found.
 SERVER_SELECTION_TIMEOUT = 30
 
-# Spec requires at least 500ms between ismaster calls.
+# Spec requires at least 500ms between hello calls.
 MIN_HEARTBEAT_INTERVAL = 0.5
 
 # Spec requires at least 60s between SRV rescans.
@@ -132,13 +132,13 @@ def partition_node(node):
 
 
 def clean_node(node):
-    """Split and normalize a node name from an ismaster response."""
+    """Split and normalize a node name from a hello response."""
     host, port = partition_node(node)
 
     # Normalize hostname to lowercase, since DNS is case-insensitive:
     # http://tools.ietf.org/html/rfc4343
     # This prevents useless rediscovery if "foo.com" is in the seed list but
-    # "FOO.com" is in the ismaster response.
+    # "FOO.com" is in the hello response.
     return host.lower(), port
 
 
@@ -977,4 +977,4 @@ def update(self, other):
                 self[key] = other[key]
 
     def cased_key(self, key):
-        return self.__casedkeys[key.lower()]
+        return self.__casedkeys[key.lower()]

pymongo/compression_support.py

@@ -34,7 +34,7 @@
 except ImportError:
     _HAVE_ZSTD = False
 
-from pymongo.hello import HelloCompat
+from pymongo.hello_compat import HelloCompat
 from pymongo.monitoring import _SENSITIVE_COMMANDS
 
 _SUPPORTED_COMPRESSORS = set(["snappy", "zlib", "zstd"])

pymongo/database.py

@@ -30,6 +30,7 @@
                             ConfigurationError,
                             InvalidName,
                             OperationFailure)
+from pymongo.hello_compat import HelloCompat
 from pymongo.message import _first_batch
 from pymongo.read_preferences import ReadPreference
 from pymongo.son_manipulator import SONManipulator
@@ -1230,7 +1231,7 @@ def error(self):
         error_msg = error.get("err", "")
         if error_msg is None:
             return None
-        if error_msg.startswith("not master"):
+        if error_msg.startswith(HelloCompat.LEGACY_ERROR):
             # Reset primary server and request check, if another thread isn't
             # doing so already.
             primary = self.__client.primary

pymongo/hello.py

@@ -14,9 +14,186 @@
 
 """Helpers for the 'hello' and legacy hello commands."""
 
+import itertools
 
-class HelloCompat:
-    CMD = 'hello'
-    LEGACY_CMD = 'ismaster'
-    PRIMARY = 'isWritablePrimary'
-    LEGACY_PRIMARY = 'ismaster'
+from bson.py3compat import imap
+from pymongo import common
+from pymongo.hello_compat import HelloCompat
+from pymongo.server_type import SERVER_TYPE
+
+
+def _get_server_type(doc):
+    """Determine the server type from a hello response."""
+    if not doc.get('ok'):
+        return SERVER_TYPE.Unknown
+
+    if doc.get('serviceId'):
+        return SERVER_TYPE.LoadBalancer
+    elif doc.get('isreplicaset'):
+        return SERVER_TYPE.RSGhost
+    elif doc.get('setName'):
+        if doc.get('hidden'):
+            return SERVER_TYPE.RSOther
+        elif doc.get(HelloCompat.PRIMARY):
+            return SERVER_TYPE.RSPrimary
+        elif doc.get(HelloCompat.LEGACY_PRIMARY):
+            return SERVER_TYPE.RSPrimary
+        elif doc.get('secondary'):
+            return SERVER_TYPE.RSSecondary
+        elif doc.get('arbiterOnly'):
+            return SERVER_TYPE.RSArbiter
+        else:
+            return SERVER_TYPE.RSOther
+    elif doc.get('msg') == 'isdbgrid':
+        return SERVER_TYPE.Mongos
+    else:
+        return SERVER_TYPE.Standalone
+
+
+class Hello(object):
+    """Parse a hello response from the server."""
+    __slots__ = ('_doc', '_server_type', '_is_writable', '_is_readable',
+                 '_awaitable')
+
+    def __init__(self, doc, awaitable=False):
+        self._server_type = _get_server_type(doc)
+        self._doc = doc
+        self._is_writable = self._server_type in (
+            SERVER_TYPE.RSPrimary,
+            SERVER_TYPE.Standalone,
+            SERVER_TYPE.Mongos,
+            SERVER_TYPE.LoadBalancer)
+
+        self._is_readable = (
+            self.server_type == SERVER_TYPE.RSSecondary
+            or self._is_writable)
+        self._awaitable = awaitable
+
+    @property
+    def document(self):
+        """The complete hello command response document.
+
+        .. versionadded:: 3.4
+        """
+        return self._doc.copy()
+
+    @property
+    def server_type(self):
+        return self._server_type
+
+    @property
+    def all_hosts(self):
+        """List of hosts, passives, and arbiters known to this server."""
+        return set(imap(common.clean_node, itertools.chain(
+            self._doc.get('hosts', []),
+            self._doc.get('passives', []),
+            self._doc.get('arbiters', []))))
+
+    @property
+    def tags(self):
+        """Replica set member tags or empty dict."""
+        return self._doc.get('tags', {})
+
+    @property
+    def primary(self):
+        """This server's opinion about who the primary is, or None."""
+        if self._doc.get('primary'):
+            return common.partition_node(self._doc['primary'])
+        else:
+            return None
+
+    @property
+    def replica_set_name(self):
+        """Replica set name or None."""
+        return self._doc.get('setName')
+
+    @property
+    def max_bson_size(self):
+        return self._doc.get('maxBsonObjectSize', common.MAX_BSON_SIZE)
+
+    @property
+    def max_message_size(self):
+        return self._doc.get('maxMessageSizeBytes', 2 * self.max_bson_size)
+
+    @property
+    def max_write_batch_size(self):
+        return self._doc.get('maxWriteBatchSize', common.MAX_WRITE_BATCH_SIZE)
+
+    @property
+    def min_wire_version(self):
+        return self._doc.get('minWireVersion', common.MIN_WIRE_VERSION)
+
+    @property
+    def max_wire_version(self):
+        return self._doc.get('maxWireVersion', common.MAX_WIRE_VERSION)
+
+    @property
+    def set_version(self):
+        return self._doc.get('setVersion')
+
+    @property
+    def election_id(self):
+        return self._doc.get('electionId')
+
+    @property
+    def cluster_time(self):
+        return self._doc.get('$clusterTime')
+
+    @property
+    def logical_session_timeout_minutes(self):
+        return self._doc.get('logicalSessionTimeoutMinutes')
+
+    @property
+    def is_writable(self):
+        return self._is_writable
+
+    @property
+    def is_readable(self):
+        return self._is_readable
+
+    @property
+    def me(self):
+        me = self._doc.get('me')
+        if me:
+            return common.clean_node(me)
+
+    @property
+    def last_write_date(self):
+        return self._doc.get('lastWrite', {}).get('lastWriteDate')
+
+    @property
+    def compressors(self):
+        return self._doc.get('compression')
+
+    @property
+    def sasl_supported_mechs(self):
+        """Supported authentication mechanisms for the current user.
+
+        For example::
+
+            >>> hello.sasl_supported_mechs
+            ["SCRAM-SHA-1", "SCRAM-SHA-256"]
+
+        """
+        return self._doc.get('saslSupportedMechs', [])
+
+    @property
+    def speculative_authenticate(self):
+        """The speculativeAuthenticate field."""
+        return self._doc.get('speculativeAuthenticate')
+
+    @property
+    def topology_version(self):
+        return self._doc.get('topologyVersion')
+
+    @property
+    def awaitable(self):
+        return self._awaitable
+
+    @property
+    def service_id(self):
+        return self._doc.get('serviceId')
+
+    @property
+    def hello_ok(self):
+        return self._doc.get('helloOk', False)

pymongo/hello_compat.py

@@ -0,0 +1,23 @@
+# Copyright 2021-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Compatibility enum of working with hello and legay hello."""
+
+class HelloCompat:
+    CMD = 'hello'
+    LEGACY_CMD = 'ismaster'
+    PRIMARY = 'isWritablePrimary'
+    LEGACY_PRIMARY = 'ismaster'
+    LEGACY_ERROR = 'not master'
+