add PEP 249 DB API constructors (#940)

* add PEP 249 DB API constructors

* docs update

Author: joe-clickhouse

CHANGELOG.md

@@ -13,6 +13,7 @@
 
 ### Bug Fixes
 
+- DB API module now provides the PEP 249 type constructors `Binary`, `Date`, `Time`, `Timestamp`, `DateFromTicks`, `TimeFromTicks`, and `TimestampFromTicks`. SQLAlchemy `LargeBinary` inserts no longer raise `AttributeError`. Addresses the Binary constructor failure in [#919](https://github.com/ClickHouse/clickhouse-connect/issues/919).
 - Fractional `DateTime64` values before the Unix epoch now serialize with the correct second. The serializer truncated negative timestamps toward zero before adding the fractional component, which shifted affected values forward by one second. This affected Python `datetime` values and accepted ISO strings in both naive datetime insert modes. See [#938](https://github.com/ClickHouse/clickhouse-connect/issues/938).
 - Parsing a nested `Variant`, `Tuple`, `Nested`, or typed `JSON` column type whose element is an `Enum` with an escaped single quote in a value name no longer corrupts the escape sequence and fails while re-parsing the element type. Closes [#878](https://github.com/ClickHouse/clickhouse-connect/issues/878).
 - `None` nested inside an `Array` or `Tuple`, or inside a `Map` when `dict_parameter_format="map"`, now renders as the SQL `NULL` keyword instead of the `\N` sentinel used for top-level values. Top-level scalar `None` binds are unchanged. Closes [#879](https://github.com/ClickHouse/clickhouse-connect/issues/879).

clickhouse_connect/dbapi/__init__.py

@@ -1,3 +1,5 @@
+from datetime import date, datetime, time
+from time import localtime
 from typing import Any
 
 from clickhouse_connect.dbapi.connection import Connection
@@ -6,6 +8,24 @@
 threadsafety = 2  # PEP 249  Threads may share the module and connections.
 paramstyle = "pyformat"  # PEP 249  Python extended format codes, e.g. ...WHERE name=%(name)s
 
+# PEP 249 type constructors.
+Date = date
+Time = time
+Timestamp = datetime
+Binary = bytes
+
+
+def DateFromTicks(ticks: float) -> date:  # noqa: N802
+    return date(*localtime(ticks)[:3])
+
+
+def TimeFromTicks(ticks: float) -> time:  # noqa: N802
+    return time(*localtime(ticks)[3:6])
+
+
+def TimestampFromTicks(ticks: float) -> datetime:  # noqa: N802
+    return datetime(*localtime(ticks)[:6])
+
 
 class Error(Exception):
     pass

docs/driver-api.mdx

@@ -792,7 +792,7 @@ For advanced use cases requiring direct access to ClickHouse HTTP interfaces wit
 
 ## Python DB-API 2.0 {#python-db-api-20}
 
-The `clickhouse_connect.dbapi` module implements the PEP 249 connection and cursor interface. It declares API level 2.0, `threadsafety=2`, and `paramstyle="pyformat"`.
+The `clickhouse_connect.dbapi` module implements the PEP 249 connection and cursor interface. It declares API level 2.0, `threadsafety=2`, and `paramstyle="pyformat"`. The module also provides the PEP 249 type constructors `Date`, `Time`, `Timestamp`, and `Binary`, and the `DateFromTicks`, `TimeFromTicks`, and `TimestampFromTicks` functions.
 
 ```python
 from clickhouse_connect import dbapi

tests/unit_tests/test_driver/test_dbapi_types.py

@@ -0,0 +1,32 @@
+from datetime import date, datetime, time
+
+import pytest
+
+import clickhouse_connect.dbapi as dbapi
+
+
+def test_binary_constructor():
+    assert dbapi.Binary(b"\x00\xff") == b"\x00\xff"
+    assert dbapi.Binary([0, 255]) == b"\x00\xff"
+
+
+def test_date_time_timestamp_constructors():
+    assert dbapi.Date(2026, 8, 5) == date(2026, 8, 5)
+    assert dbapi.Time(13, 14, 15) == time(13, 14, 15)
+    assert dbapi.Timestamp(2026, 8, 5, 13, 14, 15) == datetime(2026, 8, 5, 13, 14, 15)
+
+
+@pytest.mark.parametrize("ticks", [0, 1_799_821_913.792341])
+def test_tick_constructors_use_local_time(ticks):
+    local_datetime = datetime.fromtimestamp(ticks)
+    assert dbapi.DateFromTicks(ticks) == local_datetime.date()
+    assert dbapi.TimeFromTicks(ticks) == local_datetime.time().replace(microsecond=0)
+    assert dbapi.TimestampFromTicks(ticks) == local_datetime.replace(microsecond=0)
+
+
+def test_sqlalchemy_dialect_import_dbapi_exposes_binary():
+    pytest.importorskip("sqlalchemy")
+
+    from clickhouse_connect.cc_sqlalchemy.dialect import ClickHouseDialect
+
+    assert ClickHouseDialect.import_dbapi().Binary(b"x") == b"x"