feat: expose template API at top level

Author: NickCrews

_duckdb-stubs/__init__.pyi

@@ -43,7 +43,7 @@ if typing.TYPE_CHECKING:
         ArrowUDF,
     )
     from ._enums import ExplainTypeLiteral, RenderModeLiteral
-    from duckdb import sqltypes, func, template
+    from duckdb import sqltypes, func, _template
 
 __all__: lst[str] = [
     "BinderException",
@@ -244,10 +244,10 @@ class DuckDBPyConnection:
     def duplicate(self) -> DuckDBPyConnection: ...
     def enum_type(self, name: str, type: sqltypes.DuckDBPyType, values: lst[typing.Any]) -> sqltypes.DuckDBPyType: ...
     def execute(
-        self, query: Statement | str | template.SqlTemplate | template.CompiledSql, parameters: object = None
+        self, query: Statement | str | _template.SqlTemplate | _template.CompiledSql, parameters: object = None
     ) -> DuckDBPyConnection: ...
     def executemany(
-        self, query: Statement | str | template.SqlTemplate | template.CompiledSql, parameters: object = None
+        self, query: Statement | str | _template.SqlTemplate | _template.CompiledSql, parameters: object = None
     ) -> DuckDBPyConnection: ...
     def extract_statements(self, query: str) -> lst[Statement]: ...
     def fetch_arrow_table(self, rows_per_batch: typing.SupportsInt = 1000000) -> pyarrow.lib.Table:
@@ -331,7 +331,7 @@ class DuckDBPyConnection:
         compression: ParquetCompression | None = None,
     ) -> DuckDBPyRelation: ...
     def from_query(
-        self, query: str | template.SqlTemplate | template.CompiledSql, *, alias: str = "", params: object = None
+        self, query: str | _template.SqlTemplate | _template.CompiledSql, *, alias: str = "", params: object = None
     ) -> DuckDBPyRelation: ...
     def get_table_names(self, query: str, *, qualified: bool = False) -> set[str]: ...
     def install_extension(
@@ -362,7 +362,7 @@ class DuckDBPyConnection:
         self, rows_per_batch: typing.SupportsInt = 1000000, *, lazy: bool = False
     ) -> polars.DataFrame | polars.LazyFrame: ...
     def query(
-        self, query: str | template.SqlTemplate | template.CompiledSql, *, alias: str = "", params: object = None
+        self, query: str | _template.SqlTemplate | _template.CompiledSql, *, alias: str = "", params: object = None
     ) -> DuckDBPyRelation: ...
     def query_progress(self) -> float: ...
     def read_csv(
@@ -458,7 +458,7 @@ class DuckDBPyConnection:
     def row_type(self, fields: IntoFields) -> sqltypes.DuckDBPyType: ...
     def sql(
         self,
-        query: Statement | str | template.SqlTemplate | template.CompiledSql,
+        query: Statement | str | _template.SqlTemplate | _template.CompiledSql,
         *,
         alias: str = "",
         params: object = None,
@@ -966,7 +966,7 @@ def enum_type(
     connection: DuckDBPyConnection | None = None,
 ) -> sqltypes.DuckDBPyType: ...
 def execute(
-    query: Statement | str | template.SqlTemplate | template.CompiledSql,
+    query: Statement | str | _template.SqlTemplate | _template.CompiledSql,
     parameters: object = None,
     *,
     connection: DuckDBPyConnection | None = None,
@@ -1081,7 +1081,7 @@ def from_parquet(
     connection: DuckDBPyConnection | None = None,
 ) -> DuckDBPyRelation: ...
 def from_query(
-    query: Statement | str | template.SqlTemplate | template.CompiledSql,
+    query: Statement | str | _template.SqlTemplate | _template.CompiledSql,
     *,
     alias: str = "",
     params: object = None,
@@ -1146,7 +1146,7 @@ def project(
     df: pandas.DataFrame, *args: IntoExpr, groups: str = "", connection: DuckDBPyConnection | None = None
 ) -> DuckDBPyRelation: ...
 def query(
-    query: Statement | str | template.SqlTemplate | template.CompiledSql,
+    query: Statement | str | _template.SqlTemplate | _template.CompiledSql,
     *,
     alias: str = "",
     params: object = None,
@@ -1259,7 +1259,7 @@ def row_type(fields: IntoFields, *, connection: DuckDBPyConnection | None = None
 def rowcount(*, connection: DuckDBPyConnection | None = None) -> int: ...
 def set_default_connection(connection: DuckDBPyConnection) -> None: ...
 def sql(
-    query: Statement | str | template.SqlTemplate | template.CompiledSql,
+    query: Statement | str | _template.SqlTemplate | _template.CompiledSql,
     *,
     alias: str = "",
     params: object = None,

duckdb/__init__.py

@@ -165,6 +165,17 @@
     STRING,
     DBAPITypeObject,
 )
+from duckdb._template import (
+    CompiledSql,
+    IntoInterpolation,
+    Param,
+    ResolvedSqlTemplate,
+    SqlTemplate,
+    SupportsDuckdbTemplate,
+    compile,
+    param,
+    template,
+)
 from duckdb._version import (
     __duckdb_version__,
     __version__,
@@ -217,6 +228,7 @@
     "CatalogException",
     "CoalesceOperator",
     "ColumnExpression",
+    "CompiledSql",
     "ConnectionException",
     "ConstantExpression",
     "ConstraintException",
@@ -246,6 +258,7 @@
     "InternalException",
     "InterruptException",
     "IntervalValue",
+    "IntoInterpolation",
     "InvalidInputException",
     "InvalidTypeException",
     "LambdaExpression",
@@ -258,20 +271,24 @@
     "OperationalError",
     "OutOfMemoryException",
     "OutOfRangeException",
+    "Param",
     "ParserException",
     "PermissionException",
     "ProgrammingError",
     "PythonExceptionHandling",
     "RenderMode",
+    "ResolvedSqlTemplate",
     "SQLExpression",
     "SequenceException",
     "SerializationException",
     "ShortValue",
+    "SqlTemplate",
     "StarExpression",
     "Statement",
     "StatementType",
     "StringValue",
     "StructValue",
+    "SupportsDuckdbTemplate",
     "SyntaxException",
     "TimeTimeZoneValue",
     "TimeValue",
@@ -308,6 +325,7 @@
     "checkpoint",
     "close",
     "commit",
+    "compile",
     "connect",
     "create_function",
     "cursor",
@@ -350,6 +368,7 @@
     "load_extension",
     "map_type",
     "order",
+    "param",
     "paramstyle",
     "paramstyle",
     "pl",
@@ -373,6 +392,7 @@
     "struct_type",
     "table",
     "table_function",
+    "template",
     "tf",
     "threadsafety",
     "threadsafety",

duckdb/template.py duckdb/_template.pyduckdb/template.py renamed to duckdb/_template.py

@@ -16,6 +16,8 @@
     "CompiledSql",
     "IntoInterpolation",
     "Param",
+    "ResolvedSqlTemplate",
+    "SqlTemplate",
     "SupportsDuckdbTemplate",
     "compile",
     "param",

tests/fast/test_template_e2e.py

@@ -3,7 +3,7 @@
 import pytest
 
 import duckdb
-from duckdb.template import param, template
+from duckdb import param, template
 
 
 def test_connection_sql_accepts_sql_template() -> None:

tests/fast/test_template_python.py

@@ -4,20 +4,22 @@
 
 import pytest
 
-from duckdb.template import (
+from duckdb import (
     CompiledSql,
     IntoInterpolation,
     Param,
-    ParamInterpolation,
     ResolvedSqlTemplate,
     SqlTemplate,
     SupportsDuckdbTemplate,
     compile,
-    compile_parts,
     param,
-    parse_parts,
     template,
 )
+from duckdb._template import (
+    ParamInterpolation,
+    compile_parts,
+    parse_parts,
+)
 
 # ── helpers ───────────────────────────────────────────────────────────────────