added docs for load_json and added an example to the playground

Author: dantownsend

docs/src/piccolo/query_clauses/index.rst

@@ -14,6 +14,7 @@ by modifying the return values.
     ./limit
     ./offset
     ./order_by
+    ./output
     ./where
     ./batch
     ./freeze

docs/src/piccolo/query_clauses/output.rst

@@ -0,0 +1,60 @@
+.. _output:
+
+output
+======
+
+You can use ``output`` clauses with the following queries:
+
+* :ref:`Select`
+* :ref:`Objects`
+
+-------------------------------------------------------------------------------
+
+Select queries only
+-------------------
+
+as_json
+~~~~~~~
+
+To return the data as a JSON string:
+
+.. code-block:: python
+
+    >>> Band.select().output(as_json=True).run_sync()
+    '[{"name":"Pythonistas","manager":1,"popularity":1000,"id":1},{"name":"Rustaceans","manager":2,"popularity":500,"id":2}]'
+
+Piccolo can use `orjson <https://github.com/ijl/orjson>`_ for JSON serialisation,
+which is blazing fast, and can handle most Python types, including dates,
+datetimes, and UUIDs. To install Piccolo with orjson support use
+``pip install piccolo[orjson]``.
+
+as_list
+~~~~~~~
+
+If you're just querying a single column from a database table, you can use
+``as_list`` to flatten the results into a single list.
+
+.. code-block:: python
+
+    >>> Band.select(Band.id).output(as_list=True).run_sync()
+    [1, 2]
+
+-------------------------------------------------------------------------------
+
+Select and Objects queries
+--------------------------
+
+load_json
+~~~~~~~~~
+
+If querying JSON or JSONB columns, you can tell Piccolo to deserialise the JSON
+values automatically.
+
+.. code-block:: python
+
+    >>> RecordingStudio.select().output(load_json=True).run_sync()
+    [{'id': 1, 'name': 'Abbey Road', 'facilities': {'restaurant': True, 'mixing_desk': True}}]
+
+    >>> studio = RecordingStudio.objects().first().output(load_json=True).run_sync()
+    >>> studio.facilities
+    {'restaurant': True, 'mixing_desk': True}

docs/src/piccolo/query_types/objects.rst

@@ -117,6 +117,11 @@ order_by
 
 See  :ref:`order_by`.
 
+output
+~~~~~~
+
+See  :ref:`output`.
+
 where
 ~~~~~
 

docs/src/piccolo/query_types/select.rst

@@ -147,21 +147,7 @@ See  :ref:`order_by`.
 output
 ~~~~~~
 
-By default, the data is returned as a list of dictionaries (where each
-dictionary represents a row). This can be altered using the ``output`` method.
-
-To return the data as a JSON string:
-
-.. code-block:: python
-
-    >>> b = Band
-    >>> b.select().output(as_json=True).run_sync()
-    '[{"name":"Pythonistas","manager":1,"popularity":1000,"id":1},{"name":"Rustaceans","manager":2,"popularity":500,"id":2}]'
-
-Piccolo can use `orjson <https://github.com/ijl/orjson>`_ for JSON serialisation,
-which is blazing fast, and can handle most Python types, including dates,
-datetimes, and UUIDs. To install Piccolo with orjson support use
-``pip install piccolo[orjson]``.
+See :ref:`output`.
 
 where
 ~~~~~

piccolo/apps/playground/commands/run.py

@@ -14,6 +14,7 @@
     ForeignKey,
     Integer,
     Interval,
+    JSON,
     Numeric,
     Timestamp,
     UUID,
@@ -55,7 +56,12 @@ class DiscountCode(Table):
     active = Boolean(default=True, null=True)
 
 
-TABLES = (Manager, Band, Venue, Concert, Ticket, DiscountCode)
+class RecordingStudio(Table):
+    name = Varchar(length=100)
+    facilities = JSON()
+
+
+TABLES = (Manager, Band, Venue, Concert, Ticket, DiscountCode, RecordingStudio)
 
 
 def populate():
@@ -105,6 +111,11 @@ def populate():
     discount_code = DiscountCode(code=uuid.uuid4())
     discount_code.save().run_sync()
 
+    recording_studio = RecordingStudio(
+        name="Abbey Road", facilities={"restaurant": True, "mixing_desk": True}
+    )
+    recording_studio.save().run_sync()
+
 
 def run(
     engine: str = "sqlite",