From 1f244416a01587b7c2ff8a1e42209332b7b821cc Mon Sep 17 00:00:00 2001 From: Federico Caselli Date: Thu, 4 Jun 2020 19:53:29 +0200 Subject: [PATCH] Improve ``Rendering Bound Parameters Inline`` documentation This is mainly to make this section more discoverable by users Change-Id: I58ba19e4a9ae85b227e5b5553ba5c30c01f3e005 --- doc/build/faq/sqlexpressions.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/build/faq/sqlexpressions.rst b/doc/build/faq/sqlexpressions.rst index 7f6c8e7cad..4d2f0774c7 100644 --- a/doc/build/faq/sqlexpressions.rst +++ b/doc/build/faq/sqlexpressions.rst @@ -95,13 +95,20 @@ flag, passed to ``compile_kwargs``:: s = select([t]).where(t.c.x == 5) - print(s.compile(compile_kwargs={"literal_binds": True})) # **do not use** with untrusted input!!! + # **do not use** with untrusted input!!! + print(s.compile(compile_kwargs={"literal_binds": True})) -the above approach has the caveats that it is only supported for basic +The above approach has the caveats that it is only supported for basic types, such as ints and strings, and furthermore if a :func:`.bindparam` without a pre-set value is used directly, it won't be able to stringify that either. +This functionality is provided mainly for +logging or debugging purposes, where having the raw sql string of a query +may prove useful. Note that the ``dialect`` parameter should also +passed to the :meth:`_expression.ClauseElement.compile` method to render +the query that will be sent to the database. + To support inline literal rendering for types not supported, implement a :class:`.TypeDecorator` for the target type which includes a :meth:`.TypeDecorator.process_literal_param` method:: @@ -119,10 +126,8 @@ a :class:`.TypeDecorator` for the target type which includes a tab = Table('mytable', MetaData(), Column('x', MyFancyType())) - print( - tab.select().where(tab.c.x > 5).compile( - compile_kwargs={"literal_binds": True}) - ) + stmt = tab.select().where(tab.c.x > 5) + print(stmt.compile(compile_kwargs={"literal_binds": True})) producing output like:: -- 2.39.5