From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 5 Jul 2019 20:14:06 +0000 (-0400)
Subject: Repair json example in tutorial to suit non-present sqlite support
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=d1d538fba773d24165cec6baa949eb88c1abcfa1;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Repair json example in tutorial to suit non-present sqlite support

Change-Id: If896273adbab2e3fdb995272f6e55de420aee220
---

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index fc349fac87..21f893e54d 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -1519,30 +1519,34 @@ another function :func:`.type_coerce` which is closely related to
 :func:`.cast`, in that it sets up a Python expression as having a specific SQL
 database type, but does not render the ``CAST`` keyword or datatype on the
 database side.    :func:`.type_coerce` is particularly important when dealing
-with the :class:`.types.JSON` datatype, which on a database like SQLite is
-an "implied" datatype. Below, we use :func:`.type_coerce` to deliver a Python
-structure as a JSON string into one of SQLite's JSON functions:
+with the :class:`.types.JSON` datatype, which typicaly has an intricate
+relationship with string-oriented datatypes on different platforms and
+may not even be an explicit datatype, such as on SQLite and MariaDB.
+Below, we use :func:`.type_coerce`
+to deliver a Python structure as a JSON string into one of MySQL's JSON
+functions (note support for JSON with SQLite, which works very similarly
+to that of MySQL, is added in SQLAlchemy 1.3):
 
 .. sourcecode:: pycon+sql
 
     >>> import json
     >>> from sqlalchemy import JSON
     >>> from sqlalchemy import type_coerce
+    >>> from sqlalchemy.dialects import mysql
     >>> s = select([
     ... type_coerce(
     ...        {'some_key': {'foo': 'bar'}}, JSON
     ...    )['some_key']
     ... ])
-    >>> conn.execute(s).fetchall()
-    {opensql}SELECT JSON_QUOTE(JSON_EXTRACT(?, ?)) AS anon_1
-    ('{"some_key": {"foo": "bar"}}', '$."some_key"')
-    {stop}[({'foo': 'bar'},)]
+    >>> print(s.compile(dialect=mysql.dialect()))
+    SELECT JSON_EXTRACT(%s, %s) AS anon_1
 
-Above, SQLite's ``JSON_QUOTE`` and ``JSON_EXTRACT`` SQL functions were invoked
+Above, MySQL's ``JSON_EXTRACT`` SQL functions was invoked
 because we used :func:`.type_coerce` to indicate that our Python dictionary
 should be treated as :class:`.types.JSON`.  The Python ``__getitem__``
 operator, ``['some_key']`` in this case, became available as a result and
-allowed a ``JSON_EXTRACT`` path expression to be rendered.
+allowed a ``JSON_EXTRACT`` path expression (not shown, however in this
+case it would ultimately be ``'$."some_key"'``) to be rendered.
 
 Unions and Other Set Operations
 -------------------------------