Remove deprecated utc_tz_aware parameter#669
Conversation
joe-clickhouse
added
the
hold for 1.0.0
There was a problem hiding this comment.
Pull request overview
Removes the deprecated utc_tz_aware API surface (and its deprecation bridge introduced in #664) so tz_mode is the only supported mechanism for controlling DateTime timezone behavior across the driver.
Changes:
- Removed
utc_tz_awareparameters/properties and_resolve_tz_modedeprecation scaffolding from driver/query & client APIs. - Updated sync/async client call paths to accept/pass
tz_modeonly. - Removed unit tests covering the deprecated bridge and added a 1.0.0 breaking-change note in the changelog.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
tests/unit_tests/test_driver/test_query.py |
Removes tests/imports that specifically validated deprecated utc_tz_aware behavior. |
clickhouse_connect/driver/query.py |
Deletes utc_tz_aware bridge logic and validates tz_mode directly in QueryContext. |
clickhouse_connect/driver/httpclient.py |
Removes utc_tz_aware ctor parameter and stops passing it into Client. |
clickhouse_connect/driver/client.py |
Removes utc_tz_aware from client/query method signatures and validates tz_mode directly. |
clickhouse_connect/driver/asyncclient.py |
Removes utc_tz_aware from async method signatures and forwarding calls. |
clickhouse_connect/driver/__init__.py |
Removes deprecated param docs for create_client/create_async_client. |
CHANGELOG.md |
Adds a 1.0.0 breaking-change entry for removing utc_tz_aware. |
Comments suppressed due to low confidence (1)
CHANGELOG.md:32
- The UNRELEASED breaking-change bullet still claims
utc_tz_awareis accepted with a DeprecationWarning, but this PR removesutc_tz_awareentirely. Update or remove this bullet so UNRELEASED accurately reflects current behavior.
### Breaking Changes
- Renamed `utc_tz_aware` parameter to `tz_mode` across Client, QueryContext, and all query methods. The new `tz_mode` parameter accepts string values: `"naive_utc"` (default, was `False`), `"aware"` (was `True`), and `"schema"` (unchanged). The old `utc_tz_aware` parameter is still accepted but emits a `DeprecationWarning` and will be removed in 1.0. Passing both `tz_mode` and `utc_tz_aware` raises `ProgrammingError`. Closes [#654](https://github.com/ClickHouse/clickhouse-connect/issues/654)
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| ## 1.0.0 | ||
|
|
||
| ### Breaking Changes | ||
| - Removed the deprecated `utc_tz_aware` parameter entirely. Use `tz_mode` instead: `"naive_utc"` (default, was `False`), `"aware"` (was `True`), or `"schema"` (unchanged). Closes [#654](https://github.com/ClickHouse/clickhouse-connect/issues/654), [#665](https://github.com/ClickHouse/clickhouse-connect/issues/665) | ||
|
|
There was a problem hiding this comment.
CHANGELOG structure is inconsistent: a "1.0.0" section is placed above "UNRELEASED" even though subsequent entries are still under UNRELEASED. Typically UNRELEASED should remain the top section until the release is cut; consider moving this breaking-change entry under UNRELEASED (or moving the 1.0.0 header below UNRELEASED) until 1.0.0 is actually released/dated.
| :param tz_mode Controls timezone-aware behavior for UTC DateTime columns. "naive_utc" (default) returns | ||
| naive UTC timestamps. "aware" forces timezone-aware UTC datetimes. "schema" returns datetimes that | ||
| match the server's column definition which means timezone-aware when the column defines a timezone and naive | ||
| for bare DateTime columns. |
There was a problem hiding this comment.
Because create_client/create_async_client accept arbitrary **kwargs, callers can still pass utc_tz_aware, which will now fail with a generic TypeError (or may be mis-routed as a server setting when coming from generic_args). Consider explicitly detecting utc_tz_aware and raising a ProgrammingError with a clear message directing users to tz_mode.
| apply_server_timezone: Optional[Union[str, bool]] = None, | ||
| tz_mode: Optional[str] = None, | ||
| utc_tz_aware: Optional[Union[bool, Literal["schema"]]] = None, | ||
| show_clickhouse_errors: Optional[bool] = None, |
There was a problem hiding this comment.
tz_mode is annotated as Optional[str] here, but the codebase defines a TzMode Literal type and uses it in other public APIs (e.g., Client, AsyncClient, QueryContext). Updating this annotation to Optional[TzMode] would keep type hints consistent for users and static checkers.
| self.tz_mode = tz_mode if tz_mode is not None else "naive_utc" | ||
| if self.tz_mode not in _VALID_TZ_MODES: | ||
| raise ProgrammingError(f'tz_mode must be "naive_utc", "aware", or "schema", got "{self.tz_mode}"') |
There was a problem hiding this comment.
Timezone mode validation logic (defaulting + membership check + error message) is now duplicated here and in Client.__init__. To avoid future drift in behavior/error messages, consider centralizing validation in a shared helper (even if utc_tz_aware support is gone).
| self.tz_mode = tz_mode if tz_mode is not None else "naive_utc" | ||
| if self.tz_mode not in _VALID_TZ_MODES: | ||
| raise ProgrammingError(f'tz_mode must be "naive_utc", "aware", or "schema", got "{self.tz_mode}"') |
There was a problem hiding this comment.
This repeats the tz_mode defaulting/validation logic that also exists in QueryContext.__init__. Consider using a shared validator to keep defaults and error messaging consistent across the API surface.
Summary
Remove all
utc_tz_awaredeprecation scaffolding introduced in #664. Thetz_modeparameter is now the only way to control timezone behavior.