add regression example for missing table provider capsule behavior

Author: kosiew

examples/README.md

@@ -42,6 +42,9 @@ Here is a direct link to the file used in the examples:
 
 - [Register a Python UDF with DataFusion](./python-udf.py)
 - [Register a Python UDAF with DataFusion](./python-udaf.py)
+- [Reproduce missing table-provider capsule failures in Python integrations](./python-udtf-table-capsule-regression.py)
+    - Demonstrates how a Python UDTF and catalog consumer currently raise
+      exceptions when `__datafusion_table_provider__` is unavailable.
 
 ### Substrait Support
 

examples/python-udtf-table-capsule-regression.py

@@ -0,0 +1,38 @@
+"""Regression example highlighting missing table provider capsule behavior.
+"""
+
+from __future__ import annotations
+
+from datafusion import SessionContext, Table, udtf
+
+
+def main() -> None:
+    """Demonstrate current failure modes around table provider capsules."""
+
+    ctx = SessionContext()
+
+    @udtf("table_from_sql")
+    def table_from_sql_udtf() -> Table:
+        """Return a DataFusion Table constructed from a SQL query."""
+
+        return Table(ctx.sql("SELECT 1 AS value"))
+
+    ctx.register_udtf(table_from_sql_udtf)
+
+    try:
+        ctx.sql("SELECT * FROM table(table_from_sql())").collect()
+    except NotImplementedError as err:
+        print("Collecting from table_from_sql() failed:", err)
+
+    ctx.register_table("numbers", Table(ctx.sql("SELECT 1 AS value")))
+
+    numbers = ctx.catalog().schema("public").table("numbers")
+
+    try:
+        getattr(numbers, "__datafusion_table_provider__")
+    except AttributeError as err:
+        print("Accessing __datafusion_table_provider__ on catalog table failed:", err)
+
+
+if __name__ == "__main__":
+    main()