From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 18 Jan 2019 05:53:55 +0000 (-0500)
Subject: Add example of password URL encoding
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=855291616890b0970f22a88e68125eccdedbb466;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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 dc5a8c996b..e029531e75 100644
--- 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')