From 336b8be3c6d95cc0d3ccf850f4be865daac23eb8 Mon Sep 17 00:00:00 2001 From: Charles Leifer Date: Wed, 11 May 2016 15:26:10 -0500 Subject: [PATCH] Update API docs for the ``scalar()`` method. Refs #935 --- docs/peewee/api.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/peewee/api.rst b/docs/peewee/api.rst index 7cf879c20..86811f515 100644 --- a/docs/peewee/api.rst +++ b/docs/peewee/api.rst @@ -872,9 +872,12 @@ Query Types .. warning: This method should be implemented by subclasses - .. py:method:: scalar([as_tuple=False]) + .. py:method:: scalar([as_tuple=False[, convert=False]]) :param bool as_tuple: return the row as a tuple or a single value + :param bool convert: attempt to coerce the selected value to the + appropriate data-type based on it's associated Field type (assuming + one exists). :rtype: the resulting row, either as a single value or tuple Provide a way to retrieve single values from select queries, for instance @@ -885,6 +888,19 @@ Query Types >>> PageView.select(fn.Count(fn.Distinct(PageView.url))).scalar() 100 # <-- there are 100 distinct URLs in the pageview table + This example illustrates the use of the `convert` argument. When using + a SQLite database, datetimes are stored as strings. To select the max + datetime, and have it *returned* as a datetime, we will specify + ``convert=True``. + + .. code-block:: pycon + + >>> PageView.select(fn.MAX(PageView.timestamp)).scalar() + '2016-04-20 13:37:00.1234' + + >>> PageView.select(fn.MAX(PageView.timestamp)).scalar(convert=True) + datetime.datetime(2016, 4, 20, 13, 37, 0, 1234) + .. py:class:: SelectQuery(model_class, *selection)