Improve the documentation of json.as method

Mention that these method are more like ``type_coerce`` than
``cast``.

Fixes: #11065
Change-Id: Ia5bd4f6d5f48be9557d0504f628202e1e6ddf6d1

diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index c846dede0207deb8634bd4e11a74ac98f5e133e3..8e559be0b7ba9fc7063aa3c893ef1603930bb7e8 100644 (file)
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -2517,7 +2517,10 @@ class JSON(Indexable, TypeEngine[Any]):
             return operator, index, self.type
 
         def as_boolean(self):
-            """Cast an indexed value as boolean.
+            """Consider an indexed value as boolean.
+
+            This is similar to using :class:`_sql.type_coerce`, and will
+            usually not apply a ``CAST()``.
 
             e.g.::
 
@@ -2533,7 +2536,10 @@ class JSON(Indexable, TypeEngine[Any]):
             return self._binary_w_type(Boolean(), "as_boolean")
 
         def as_string(self):
-            """Cast an indexed value as string.
+            """Consider an indexed value as string.
+
+            This is similar to using :class:`_sql.type_coerce`, and will
+            usually not apply a ``CAST()``.
 
             e.g.::
 
@@ -2550,7 +2556,10 @@ class JSON(Indexable, TypeEngine[Any]):
             return self._binary_w_type(Unicode(), "as_string")
 
         def as_integer(self):
-            """Cast an indexed value as integer.
+            """Consider an indexed value as integer.
+
+            This is similar to using :class:`_sql.type_coerce`, and will
+            usually not apply a ``CAST()``.
 
             e.g.::
 
@@ -2566,7 +2575,10 @@ class JSON(Indexable, TypeEngine[Any]):
             return self._binary_w_type(Integer(), "as_integer")
 
         def as_float(self):
-            """Cast an indexed value as float.
+            """Consider an indexed value as float.
+
+            This is similar to using :class:`_sql.type_coerce`, and will
+            usually not apply a ``CAST()``.
 
             e.g.::
 
@@ -2582,7 +2594,10 @@ class JSON(Indexable, TypeEngine[Any]):
             return self._binary_w_type(Float(), "as_float")
 
         def as_numeric(self, precision, scale, asdecimal=True):
-            """Cast an indexed value as numeric/decimal.
+            """Consider an indexed value as numeric/decimal.
+
+            This is similar to using :class:`_sql.type_coerce`, and will
+            usually not apply a ``CAST()``.
 
             e.g.::
 
@@ -2601,7 +2616,10 @@ class JSON(Indexable, TypeEngine[Any]):
             )
 
         def as_json(self):
-            """Cast an indexed value as JSON.
+            """Consider an indexed value as JSON.
+
+            This is similar to using :class:`_sql.type_coerce`, and will
+            usually not apply a ``CAST()``.
 
             e.g.::