Add emphasis to URL documentation re: URL encoding

Fixes: #5715
Change-Id: I2ac16541d34f49b25070e00c43596bcd71aff72d
(cherry picked from commit f6188d31998321a857078d6a61672aae1f98e312)

diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index c8a57ee7b1c923932b1d5373c7656a7795a13a04..18298efadf4b6c74516598bcd953d135fa9a2d4a 100644 (file)
--- a/doc/build/core/engines.rst
+++ b/doc/build/core/engines.rst
@@ -71,13 +71,17 @@ the database using all lowercase letters. If not specified, a "default" DBAPI
 will be imported if available - this default is typically the most widely
 known driver available for that backend.
 
-As the URL is like any other URL, special characters such as those that
-may be used in the password need to be URL encoded.   Below is an example
-of a URL that includes the password ``"kx%jj5/g"``::
+As the URL is like any other URL, **special characters such as those that may
+be used in the password need to be URL encoded to be parsed correctly.**. Below
+is an example of a URL that includes the password ``"kx%jj5/g"``, where the
+percent sign and slash characters are represented as ``%25`` and ``%2F``,
+respectively::
 
   postgresql+pg8000://dbuser:kx%25jj5%2Fg@pghost10/appdb
 
-The encoding for the above password can be generated using ``urllib``::
+
+The encoding for the above password can be generated using
+`urllib.parse <https://docs.python.org/3/library/urllib.parse.html>`_::
 
   >>> import urllib.parse
   >>> urllib.parse.quote_plus("kx%jj5/g")

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index 6028a1d7eaf1c119e8624873764aca19500e8d8e..eb9f5ae0b0e86f92d0761d02680ce9127540f191 100644 (file)
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -85,13 +85,18 @@ default_strategy = "plain"
 def create_engine(*args, **kwargs):
     """Create a new :class:`_engine.Engine` instance.
 
-    The standard calling form is to send the URL as the
+    The standard calling form is to send the :ref:`URL <database_urls>` as the
     first positional argument, usually a string
     that indicates database dialect and connection arguments::
 
-
         engine = create_engine("postgresql://scott:tiger@localhost/test")
 
+    .. note::
+
+        Please review :ref:`database_urls` for general guidelines in composing
+        URL strings.  In particular, special characters, such as those often
+        part of passwords, must be URL encoded to be properly parsed.
+
     Additional keyword arguments may then follow it which
     establish various options on the resulting :class:`_engine.Engine`
     and its underlying :class:`.Dialect` and :class:`_pool.Pool`