From 14c73685ba909838fb90d762d465e7ae8d067c15 Mon Sep 17 00:00:00 2001 From: Gord Thompson Date: Thu, 24 Nov 2022 10:38:20 -0700 Subject: Add recommendation for URL.create() re: escaping Let users know that URL.create() can build the whole connection URL instead of making them escape things like passwords ad-hoc. includes some general cleanup of URL docstring by mike Change-Id: Ic71bb0201fecf30e1db11e006c269f2d041b5439 --- lib/sqlalchemy/engine/url.py | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) (limited to 'lib/sqlalchemy') diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py index cca31edd0..820e700f3 100644 --- a/lib/sqlalchemy/engine/url.py +++ b/lib/sqlalchemy/engine/url.py @@ -46,15 +46,21 @@ class URL(NamedTuple): """ Represent the components of a URL used to connect to a database. - This object is suitable to be passed directly to a - :func:`_sa.create_engine` call. The fields of the URL are parsed from a - string by the :func:`.make_url` function. The string format of the URL - generally follows `RFC-1738 `_, with - some exceptions. - - To create a new :class:`_engine.URL` object, use the - :func:`.make_url` function. To construct a :class:`_engine.URL` - programmatically, use the :meth:`_engine.URL.create` constructor. + URLs are typically constructed from a fully formatted URL string, where the + :func:`.make_url` function is used internally by the + :func:`_sa.create_engine` function in order to parse the URL string into + its individual components, which are then used to construct a new + :class:`.URL` object. When parsing from a formatted URL string, the parsing + format generally follows + `RFC-1738 `_, with some exceptions. + + A :class:`_engine.URL` object may also be produced directly, either by + using the :func:`.make_url` function with a fully formed URL string, or + by using the :meth:`_engine.URL.create` constructor in order + to construct a :class:`_engine.URL` programmatically given individual + fields. The resulting :class:`.URL` object may be passed directly to + :func:`_sa.create_engine` in place of a string argument, which will bypass + the usage of :func:`.make_url` within the engine's creation process. .. versionchanged:: 1.4 -- cgit v1.2.1