From 8c1b073b596af23c02020879219b4e85f15a836d Mon Sep 17 00:00:00 2001 From: Adam Johnson Date: Fri, 6 Mar 2020 12:02:08 +0000 Subject: [PATCH] Doc'd return values of as_sql() for Func and query expressions. --- docs/ref/models/expressions.txt | 4 +++- docs/ref/models/lookups.txt | 10 ++++++---- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index f0f0b16f12e..be89a2435f1 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -314,7 +314,9 @@ The ``Func`` API is as follows: .. method:: as_sql(compiler, connection, function=None, template=None, arg_joiner=None, **extra_context) - Generates the SQL for the database function. + Generates the SQL fragment for the database function. Returns a tuple + ``(sql, params)``, where ``sql`` is the SQL string, and ``params`` is + the list or tuple of query parameters. The ``as_vendor()`` methods should use the ``function``, ``template``, ``arg_joiner``, and any other ``**extra_context`` parameters to diff --git a/docs/ref/models/lookups.txt b/docs/ref/models/lookups.txt index aae5ba96c4f..0846ade640b 100644 --- a/docs/ref/models/lookups.txt +++ b/docs/ref/models/lookups.txt @@ -86,10 +86,12 @@ following methods: .. method:: as_sql(compiler, connection) - Responsible for producing the query string and parameters for the expression. - The ``compiler`` is an ``SQLCompiler`` object, which has a ``compile()`` - method that can be used to compile other expressions. The ``connection`` is - the connection used to execute the query. + Generates the SQL fragment for the expression. Returns a tuple + ``(sql, params)``, where ``sql`` is the SQL string, and ``params`` is the + list or tuple of query parameters. The ``compiler`` is an ``SQLCompiler`` + object, which has a ``compile()`` method that can be used to compile other + expressions. The ``connection`` is the connection used to execute the + query. Calling ``expression.as_sql()`` is usually incorrect - instead ``compiler.compile(expression)`` should be used. The ``compiler.compile()``