Add emphasis to URL documentation re: URL encoding

Fixes: #5715
Change-Id: I2ac16541d34f49b25070e00c43596bcd71aff72d

diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index 6bcd14ac2a6428f51677c85b2946e3322a438af2..7cfa1bddd012ddf1d7e925f4fb9feef60279ca20 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/create.py b/lib/sqlalchemy/engine/create.py
index dd732a09aec52a896de1efbc06ba03853c8a8d48..381e0879d7b0c83589e4137f0a9a0884afa674d3 100644 (file)
--- a/lib/sqlalchemy/engine/create.py
+++ b/lib/sqlalchemy/engine/create.py
@@ -45,13 +45,18 @@ from ..sql import compiler
 def create_engine(url, **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`