De-emphasize notion of "default driver" (DBAPI)

Fixes: #6960

Even though a default driver still exists for
each dialect, remove most usages of `dialect://`
to encourage users to explicitly specify
`dialect+driver://`

Change-Id: I0ad42167582df509138fca64996bbb53e379b1af

5 files changed, 15 insertions, 15 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 41c5f4753..ef6282525 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -1887,7 +1887,7 @@ class Transaction(TransactionalContext):
     :class:`_engine.Connection`::
 
         from sqlalchemy import create_engine
-        engine = create_engine("postgresql://scott:tiger@localhost/test")
+        engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
         connection = engine.connect()
         trans = connection.begin()
         connection.execute(text("insert into x (a, b) values (1, 2)"))
@@ -1914,7 +1914,7 @@ class Transaction(TransactionalContext):
 
     .. index::
       single: thread safety; Transaction
-    """
+    """  # noqa
 
     __slots__ = ()
 
@@ -2413,7 +2413,7 @@ class Engine(ConnectionEventsTarget, log.Identified):
             from sqlalchemy import event
             from sqlalchemy.engine import Engine
 
-            primary_engine = create_engine("mysql://")
+            primary_engine = create_engine("mysql+mysqldb://")
             shard1 = primary_engine.execution_options(shard_id="shard1")
             shard2 = primary_engine.execution_options(shard_id="shard2")
 
diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py
index 6e5a07098..bb657202f 100644
--- a/lib/sqlalchemy/engine/create.py
+++ b/lib/sqlalchemy/engine/create.py
@@ -42,7 +42,7 @@ def create_engine(url, **kwargs):
     first positional argument, usually a string
     that indicates database dialect and connection arguments::
 
-        engine = create_engine("postgresql://scott:tiger@localhost/test")
+        engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
 
     .. note::
 
@@ -55,7 +55,7 @@ def create_engine(url, **kwargs):
     and its underlying :class:`.Dialect` and :class:`_pool.Pool`
     constructs::
 
-        engine = create_engine("mysql://scott:tiger@hostname/dbname",
+        engine = create_engine("mysql+mysqldb://scott:tiger@hostname/dbname",
                                     encoding='latin1', echo=True)
 
     The string form of the URL is
diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py
index cfb616aff..57628066d 100644
--- a/lib/sqlalchemy/engine/events.py
+++ b/lib/sqlalchemy/engine/events.py
@@ -30,7 +30,7 @@ class ConnectionEvents(event.Events):
                                                         executemany):
             log.info("Received statement: %s", statement)
 
-        engine = create_engine('postgresql://scott:tiger@localhost/test')
+        engine = create_engine('postgresql+psycopg2://scott:tiger@localhost/test')
         event.listen(engine, "before_cursor_execute", before_cursor_execute)
 
     or with a specific :class:`_engine.Connection`::
@@ -88,7 +88,7 @@ class ConnectionEvents(event.Events):
       and parameters.  See those methods for a description of
       specific return arguments.
 
-    """
+    """  # noqa
 
     _target_class_doc = "SomeEngine"
     _dispatch_target = ConnectionEventsTarget
diff --git a/lib/sqlalchemy/engine/mock.py b/lib/sqlalchemy/engine/mock.py
index 5da716b6b..731dacc33 100644
--- a/lib/sqlalchemy/engine/mock.py
+++ b/lib/sqlalchemy/engine/mock.py
@@ -62,7 +62,7 @@ def create_mock_engine(url, executor, **kw):
         def dump(sql, *multiparams, **params):
             print(sql.compile(dialect=engine.dialect))
 
-        engine = create_mock_engine('postgresql://', dump)
+        engine = create_mock_engine('postgresql+psycopg2://', dump)
         metadata.create_all(engine, checkfirst=False)
 
     :param url: A string URL which typically needs to contain only the
diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py
index be330eb6c..7f09b1eac 100644
--- a/lib/sqlalchemy/engine/url.py
+++ b/lib/sqlalchemy/engine/url.py
@@ -286,10 +286,10 @@ class URL(
         E.g.::
 
             >>> from sqlalchemy.engine import make_url
-            >>> url = make_url("postgresql://user:pass@host/dbname")
+            >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
             >>> url = url.update_query_string("alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
             >>> str(url)
-            'postgresql://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
+            'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
 
         :param query_string: a URL escaped query string, not including the
          question mark.
@@ -320,10 +320,10 @@ class URL(
         E.g.::
 
             >>> from sqlalchemy.engine import make_url
-            >>> url = make_url("postgresql://user:pass@host/dbname")
+            >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
             >>> url = url.update_query_pairs([("alt_host", "host1"), ("alt_host", "host2"), ("ssl_cipher", "/path/to/crt")])
             >>> str(url)
-            'postgresql://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
+            'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
 
         :param key_value_pairs: A sequence of tuples containing two strings
          each.
@@ -389,10 +389,10 @@ class URL(
 
 
             >>> from sqlalchemy.engine import make_url
-            >>> url = make_url("postgresql://user:pass@host/dbname")
+            >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
             >>> url = url.update_query_dict({"alt_host": ["host1", "host2"], "ssl_cipher": "/path/to/crt"})
             >>> str(url)
-            'postgresql://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
+            'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
 
 
         :param query_parameters: A dictionary with string keys and values
@@ -485,7 +485,7 @@ class URL(
 
 
             >>> from sqlalchemy.engine import make_url
-            >>> url = make_url("postgresql://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
+            >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
             >>> url.query
             immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'})
             >>> url.normalized_query