fixup: try_cast: v5

- Tweak docs to be explicit that only MSSQL
  is currently supported.
- Update try_cast() docstring to better follow
the conventions of cast()
(and just be better in general)
- export try_cast from sql/__init__.py

diff --git a/doc/build/changelog/unreleased_20/9752.rst b/doc/build/changelog/unreleased_20/9752.rst
index 0c095fcedcda2f1bc340d3a35f5da300dd654bf2..6e9bb3512310f6f36141f35c3704452026a22c24 100644 (file)
--- a/doc/build/changelog/unreleased_20/9752.rst
+++ b/doc/build/changelog/unreleased_20/9752.rst
@@ -3,11 +3,13 @@
     :tickets: 9752
 
 
-    Generalized the MSSQL :func:`.try_cast` function to any dialect.
+    Generalized the MSSQL :func:`.try_cast` function so that other
+    extension dialects can use it (MSSQL is the only builtin dialect
+    that currently supports it).
+
     This implements a cast where
     un-castable values are returned as NULL, instead of raising an error.
-    Now this function can be taken advantage of by third party dialects
-    that also support this function, such as
+    These are a few third party dialects that could implement this:
 
     * ``SAFE_CAST`` in Google BigQuery
     * ``TRY_CAST`` in DuckDB

diff --git a/lib/sqlalchemy/sql/__init__.py b/lib/sqlalchemy/sql/__init__.py
index 96cffed7d0e1376bc5ea95625b778f49d930748f..c4c8c7d27a79378febfe6a258a705e9f82eaecf5 100644 (file)
--- a/lib/sqlalchemy/sql/__init__.py
+++ b/lib/sqlalchemy/sql/__init__.py
@@ -93,6 +93,7 @@ from .expression import tablesample as tablesample
 from .expression import text as text
 from .expression import true as true
 from .expression import True_ as True_
+from .expression import try_cast as try_cast
 from .expression import tuple_ as tuple_
 from .expression import type_coerce as type_coerce
 from .expression import union as union

diff --git a/lib/sqlalchemy/sql/_elements_constructors.py b/lib/sqlalchemy/sql/_elements_constructors.py
index 9a52e59e4e49abe82d0159438ff097b540c36744..e85d46818f9e1540066c60daeec67821e1ff39f2 100644 (file)
--- a/lib/sqlalchemy/sql/_elements_constructors.py
+++ b/lib/sqlalchemy/sql/_elements_constructors.py
@@ -896,6 +896,7 @@ def cast(
 
         :func:`.try_cast` - an alternative to CAST that results in
         NULLs when the cast fails, instead of raising an error.
+        Only supported by some dialects.
 
         :func:`.type_coerce` - an alternative to CAST that coerces the type
         on the Python side only, which is often sufficient to generate the
@@ -907,11 +908,21 @@ def cast(
 
 
 def try_cast(*arg, **kw):
-    """Create a TRY_CAST expression.
+    """Produce a ``TRY_CAST`` expression.
+
+    :func:`.try_cast` returns an instance of :class:`.TryCast`.
+
+    The only builtin dialect that supports :class:`.TryCast` is
+    Microsoft SQL (other third party dialects may support it as well).
 
     :class:`.TryCast` is a subclass of SQLAlchemy's :class:`.Cast`
-    construct, and works in the same way, except that the SQL expression
-    rendered is "TRY_CAST" rather than "CAST"::
+    construct, and works in the same way, except in regards to error
+    handling. If the function encounters an un-castable value
+    (for instance when trying to convert the string "hi" to an INT)
+    then normal :class:`.Cast` raises an error. :class:`.TryCast`
+    instead returns a NULL value.
+
+    E.g.::
 
         from sqlalchemy import select, try_cast, Numeric
 
@@ -919,12 +930,12 @@ def try_cast(*arg, **kw):
             try_cast(product_table.c.unit_price, Numeric(10, 4))
         )
 
-    The above would render with mssql as::
+    The above would render with Microsoft SQL as::
 
         SELECT TRY_CAST (product_table.unit_price AS NUMERIC(10, 4))
         FROM product_table
 
-    .. versionadded:: 2.1.0
+    .. versionadded:: 2.0.14
 
     """
     return TryCast(*arg, **kw)