From: Mike Bayer Date: Sun, 14 Feb 2021 19:36:27 +0000 (-0500) Subject: Add emphasis to URL documentation re: URL encoding X-Git-Tag: rel_1_3_24~22 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5b4116890802ed5a73c5eb27b13c2862d030b2fa;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 c8a57ee7b1..18298efadf 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/__init__.py b/lib/sqlalchemy/engine/__init__.py index 6028a1d7ea..eb9f5ae0b0 100644 --- 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 ` 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`