From f6188d31998321a857078d6a61672aae1f98e312 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 14 Feb 2021 14:36:27 -0500 Subject: [PATCH] Add emphasis to URL documentation re: URL encoding Fixes: #5715 Change-Id: I2ac16541d34f49b25070e00c43596bcd71aff72d --- doc/build/core/engines.rst | 12 ++++++++---- lib/sqlalchemy/engine/create.py | 9 +++++++-- 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index 6bcd14ac2a..7cfa1bddd0 100644 --- 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 `_:: >>> 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 dd732a09ae..381e0879d7 100644 --- 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 ` 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` -- 2.47.2