Add example of password URL encoding

Fixes: #4452
Change-Id: I6d6ef36c4a0aa1e7c064b8aed289a1ce79b5120f
(cherry picked from commit 77a932e321ce402a2c4550d4788c5fdeab8aaa9b)

diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index dc5a8c996bc9a0867c3812938d9a86718f2022f1..e029531e759b3bd16f7abd9637ff61c27225403a 100644 (file)
--- a/doc/build/core/engines.rst
+++ b/doc/build/core/engines.rst
@@ -71,9 +71,21 @@ 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"``::
+
+  postgresql+pg8000://dbuser:kx%25jj5%2Fg@pghost10/appdb
+
+The encoding for the password can be generated using ``urllib``::
+
+  >>> import urllib.parse
+  >>> urllib.parse.quote_plus("kx%jj5/g")
+  'kx%25jj5%2Fg'
+
 Examples for common connection styles follow below.  For a full index of
-detailed information on all included dialects as well as links to third-party dialects, see
-:ref:`dialect_toplevel`.
+detailed information on all included dialects as well as links to third-party
+dialects, see :ref:`dialect_toplevel`.
 
 PostgreSQL
 ----------
@@ -155,7 +167,7 @@ And for an absolute file path, the three slashes are followed by the absolute pa
 
     #Unix/Mac - 4 initial slashes in total
     engine = create_engine('sqlite:////absolute/path/to/foo.db')
-    #Windows 
+    #Windows
     engine = create_engine('sqlite:///C:\\path\\to\\foo.db')
     #Windows alternative using raw string
     engine = create_engine(r'sqlite:///C:\path\to\foo.db')