Rename MongoEngineConnectionError to ConnectionFailure (#2111)

I originally changed the exception name from `ConnectionError` to
`MongoEngineConnectionError` in
b02904ee75,
inspired by landscape.io's package health report, which argued that
`ConnectionError` is already a built-in exception in Python 3 (which it is:
https://docs.python.org/3/library/exceptions.html#ConnectionError).

I do agree that we shouldn't override built-in exceptions. [0] That said, it’s
silly to add a "MongoEngine" prefix to any class within the `mongoengine`
module (and *especially* to *just one* exception class out of many). I've
decided to do what PyMongo does (
8855a510a8/pymongo/errors.py (L59))
and call this exception `ConnectionFailure`.

Note that this is a breaking change and people will need to rename
`MongoEngineConnectionError`s in their code to `ConnectionFailure`. Moreover,
if they use PyMongo's `ConnectionFailure` for anything, they'll need to take
    extra care to avoid conflicts, e.g. by using:
```
from mongoengine import ConnectionFailure as MongoEngineConnectionFailure
```

[0] Note that some popular packages still overwrite `ConnectionError`, e.g.
4983a9bde3/requests/exceptions.py (L32)
or
0be4d29206/redis/exceptions.py (L8)

docs/changelog.rst

@@ -6,6 +6,8 @@ Changelog
 Development
 ===========
 - (Fill this out as you fix issues and develop your features).
+- BREAKING CHANGE: Renamed `MongoEngineConnectionError` to `ConnectionFailure` #2111
+  - If you catch/use `MongoEngineConnectionError` in your code, you'll have to rename it.
 - BREAKING CHANGE: Positional arguments when instantiating a document are no longer supported. #2103
   - From now on keyword arguments (e.g. `Doc(field_name=value)`) are required.
 - The codebase is now formatted using `black`. #2109

mongoengine/connection.py

@@ -5,7 +5,7 @@ import six
 __all__ = [
     "DEFAULT_CONNECTION_NAME",
     "DEFAULT_DATABASE_NAME",
-    "MongoEngineConnectionError",
+    "ConnectionFailure",
     "connect",
     "disconnect",
     "disconnect_all",
@@ -27,7 +27,7 @@ _dbs = {}
 READ_PREFERENCE = ReadPreference.PRIMARY
 
 
-class MongoEngineConnectionError(Exception):
+class ConnectionFailure(Exception):
     """Error raised when the database connection can't be established or
     when a connection with a requested alias can't be retrieved.
     """
@@ -252,13 +252,13 @@ def get_connection(alias=DEFAULT_CONNECTION_NAME, reconnect=False):
         return _connections[alias]
 
     # Validate that the requested alias exists in the _connection_settings.
-    # Raise MongoEngineConnectionError if it doesn't.
+    # Raise ConnectionFailure if it doesn't.
     if alias not in _connection_settings:
         if alias == DEFAULT_CONNECTION_NAME:
             msg = "You have not defined a default connection"
         else:
             msg = 'Connection with alias "%s" has not been defined' % alias
-        raise MongoEngineConnectionError(msg)
+        raise ConnectionFailure(msg)
 
     def _clean_settings(settings_dict):
         irrelevant_fields_set = {
@@ -305,14 +305,12 @@ def get_connection(alias=DEFAULT_CONNECTION_NAME, reconnect=False):
 def _create_connection(alias, connection_class, **connection_settings):
     """
     Create the new connection for this alias. Raise
-    MongoEngineConnectionError if it can't be established.
+    ConnectionFailure if it can't be established.
     """
     try:
         return connection_class(**connection_settings)
     except Exception as e:
-        raise MongoEngineConnectionError(
+        raise ConnectionFailure("Cannot connect to database %s :\n%s" % (alias, e))
-            "Cannot connect to database %s :\n%s" % (alias, e)
-        )
 
 
 def _find_existing_connection(connection_settings):
@@ -393,7 +391,7 @@ def connect(db=None, alias=DEFAULT_CONNECTION_NAME, **kwargs):
                 u"A different connection with alias `{}` was already "
                 u"registered. Use disconnect() first"
             ).format(alias)
-            raise MongoEngineConnectionError(err_msg)
+            raise ConnectionFailure(err_msg)
     else:
         register_connection(alias, db, **kwargs)
 

tests/test_connection.py

@@ -23,7 +23,7 @@ from mongoengine import (
 )
 import mongoengine.connection
 from mongoengine.connection import (
-    MongoEngineConnectionError,
+    ConnectionFailure,
     get_db,
     get_connection,
     disconnect,
@@ -92,10 +92,10 @@ class ConnectionTest(unittest.TestCase):
         disconnect("db1")
         disconnect("db2")
 
-        with self.assertRaises(MongoEngineConnectionError):
+        with self.assertRaises(ConnectionFailure):
             list(History1.objects().as_pymongo())
 
-        with self.assertRaises(MongoEngineConnectionError):
+        with self.assertRaises(ConnectionFailure):
             list(History2.objects().as_pymongo())
 
         connect("db1", alias="db1")
@@ -149,7 +149,7 @@ class ConnectionTest(unittest.TestCase):
     def test_connect_fails_if_connect_2_times_with_default_alias(self):
         connect("mongoenginetest")
 
-        with self.assertRaises(MongoEngineConnectionError) as ctx_err:
+        with self.assertRaises(ConnectionFailure) as ctx_err:
             connect("mongoenginetest2")
         self.assertEqual(
             "A different connection with alias `default` was already registered. Use disconnect() first",
@@ -159,7 +159,7 @@ class ConnectionTest(unittest.TestCase):
     def test_connect_fails_if_connect_2_times_with_custom_alias(self):
         connect("mongoenginetest", alias="alias1")
 
-        with self.assertRaises(MongoEngineConnectionError) as ctx_err:
+        with self.assertRaises(ConnectionFailure) as ctx_err:
             connect("mongoenginetest2", alias="alias1")
 
         self.assertEqual(
@@ -175,7 +175,7 @@ class ConnectionTest(unittest.TestCase):
         db_alias = "alias1"
         connect(db=db_name, alias=db_alias, host="localhost", port=27017)
 
-        with self.assertRaises(MongoEngineConnectionError):
+        with self.assertRaises(ConnectionFailure):
             connect(host="mongodb://localhost:27017/%s" % db_name, alias=db_alias)
 
     def test_connect_passes_silently_connect_multiple_times_with_same_config(self):
@@ -353,7 +353,7 @@ class ConnectionTest(unittest.TestCase):
 
         self.assertIsNone(History._collection)
 
-        with self.assertRaises(MongoEngineConnectionError) as ctx_err:
+        with self.assertRaises(ConnectionFailure) as ctx_err:
             History.objects.first()
         self.assertEqual(
             "You have not defined a default connection", str(ctx_err.exception)
@@ -379,7 +379,7 @@ class ConnectionTest(unittest.TestCase):
         disconnect()
 
         # Make sure save doesnt work at this stage
-        with self.assertRaises(MongoEngineConnectionError):
+        with self.assertRaises(ConnectionFailure):
             User(name="Wont work").save()
 
         # Save in db2
@@ -433,10 +433,10 @@ class ConnectionTest(unittest.TestCase):
         self.assertEqual(len(dbs), 0)
         self.assertEqual(len(connection_settings), 0)
 
-        with self.assertRaises(MongoEngineConnectionError):
+        with self.assertRaises(ConnectionFailure):
             History.objects.first()
 
-        with self.assertRaises(MongoEngineConnectionError):
+        with self.assertRaises(ConnectionFailure):
             History1.objects.first()
 
     def test_disconnect_all_silently_pass_if_no_connection_exist(self):
@@ -557,7 +557,7 @@ class ConnectionTest(unittest.TestCase):
         """
         register_connection("testdb", "mongoenginetest2")
 
-        self.assertRaises(MongoEngineConnectionError, get_connection)
+        self.assertRaises(ConnectionFailure, get_connection)
         conn = get_connection("testdb")
         self.assertIsInstance(conn, pymongo.mongo_client.MongoClient)
 

tests/test_replicaset_connection.py

@@ -4,7 +4,7 @@ from pymongo import ReadPreference
 from pymongo import MongoClient
 
 import mongoengine
-from mongoengine.connection import MongoEngineConnectionError
+from mongoengine.connection import ConnectionFailure
 
 
 CONN_CLASS = MongoClient
@@ -32,7 +32,7 @@ class ConnectionTest(unittest.TestCase):
                 host="mongodb://localhost/mongoenginetest?replicaSet=rs",
                 read_preference=READ_PREF,
             )
-        except MongoEngineConnectionError as e:
+        except ConnectionFailure as e:
             return
 
         if not isinstance(conn, CONN_CLASS):