confluent-sql 0.8.0__tar.gz → 0.9.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/CHANGELOG.md +29 -1
  2. confluent_sql-0.9.0/CLAUDE.md +115 -0
  3. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/DBAPI_EXTENSIONS.md +24 -20
  4. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/PKG-INFO +42 -8
  5. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/README.md +41 -7
  6. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/tableflow_gcs_example.py +8 -6
  7. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/tableflow_lifecycle_example.py +6 -4
  8. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/pyproject.toml +1 -0
  9. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/service.yml +4 -3
  10. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/__init__.py +16 -1
  11. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/__version__.py +1 -1
  12. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/artifacts.py +109 -65
  13. confluent_sql-0.9.0/src/confluent_sql/connect_options.py +111 -0
  14. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/connection.py +676 -1043
  15. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/connectors.py +122 -151
  16. confluent_sql-0.9.0/src/confluent_sql/context.py +51 -0
  17. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/cursor.py +63 -16
  18. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/exceptions.py +121 -6
  19. confluent_sql-0.9.0/src/confluent_sql/oauth/__init__.py +24 -0
  20. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/oauth/callback_server.py +1 -1
  21. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/oauth/holder.py +31 -1
  22. confluent_sql-0.9.0/src/confluent_sql/polling.py +122 -0
  23. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/result_readers.py +52 -18
  24. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/retry.py +23 -2
  25. confluent_sql-0.9.0/src/confluent_sql/service_client.py +302 -0
  26. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/tableflow.py +343 -8
  27. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/utils.py +17 -10
  28. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/conftest.py +3 -4
  29. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/conftest.py +90 -0
  30. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_connection.py +50 -3
  31. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_connector.py +12 -8
  32. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_cursor.py +51 -14
  33. confluent_sql-0.9.0/tests/integration/test_global_key_organization.py +97 -0
  34. confluent_sql-0.9.0/tests/integration/test_infer_cloud.py +198 -0
  35. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_oauth.py +22 -17
  36. confluent_sql-0.9.0/tests/integration/test_oauth_ambiguous_org.py +73 -0
  37. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_oauth_rejected_org.py +4 -2
  38. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_oauth_user_identity.py +3 -2
  39. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_oauth_user_mismatch.py +9 -3
  40. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_tableflow.py +5 -4
  41. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/conftest.py +3 -1
  42. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/oauth/test_holder_unit.py +61 -0
  43. confluent_sql-0.9.0/tests/unit/test_artifacts_connection_unit.py +143 -0
  44. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_artifacts_unit.py +190 -58
  45. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_changelog_unit.py +21 -20
  46. confluent_sql-0.9.0/tests/unit/test_connect_options_unit.py +119 -0
  47. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_connection_byoidc_unit.py +9 -13
  48. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_connection_close_unit.py +14 -42
  49. confluent_sql-0.9.0/tests/unit/test_connection_connector_unit.py +94 -0
  50. confluent_sql-0.9.0/tests/unit/test_connection_controlplane_surfaces_unit.py +257 -0
  51. confluent_sql-0.9.0/tests/unit/test_connection_infer_cloud_unit.py +378 -0
  52. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_connection_oauth_unit.py +311 -37
  53. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_connection_unit.py +346 -464
  54. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_connection_unit_properties.py +1 -1
  55. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_connectors_connection_unit.py +268 -101
  56. confluent_sql-0.9.0/tests/unit/test_context_unit.py +73 -0
  57. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_cursor_unit.py +85 -5
  58. confluent_sql-0.9.0/tests/unit/test_package_unit.py +33 -0
  59. confluent_sql-0.9.0/tests/unit/test_poll_until_forwards_ctx_unit.py +135 -0
  60. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_polling_unit.py +149 -1
  61. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_result_readers_unit.py +240 -1
  62. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_retry_unit.py +84 -0
  63. confluent_sql-0.9.0/tests/unit/test_service_client_unit.py +671 -0
  64. confluent_sql-0.9.0/tests/unit/test_tableflow_api_unit.py +678 -0
  65. confluent_sql-0.9.0/tests/unit/test_tableflow_connection_unit.py +222 -0
  66. confluent_sql-0.9.0/tests/unit/test_utils_unit.py +83 -0
  67. confluent_sql-0.8.0/CLAUDE.md +0 -72
  68. confluent_sql-0.8.0/src/confluent_sql/oauth/__init__.py +0 -56
  69. confluent_sql-0.8.0/src/confluent_sql/polling.py +0 -57
  70. confluent_sql-0.8.0/src/confluent_sql/service_api.py +0 -33
  71. confluent_sql-0.8.0/tests/unit/test_artifacts_connection_unit.py +0 -231
  72. confluent_sql-0.8.0/tests/unit/test_connection_connector_unit.py +0 -164
  73. confluent_sql-0.8.0/tests/unit/test_package_unit.py +0 -18
  74. confluent_sql-0.8.0/tests/unit/test_tableflow_connection_unit.py +0 -698
  75. confluent_sql-0.8.0/tests/unit/test_utils_unit.py +0 -35
  76. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/.claude/rules/software-engineering.md +0 -0
  77. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/.github/CODEOWNERS +0 -0
  78. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/.gitignore +0 -0
  79. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/.semaphore/publish_to_pypi.yml +0 -0
  80. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/.semaphore/semaphore.yml +0 -0
  81. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/ARCHITECTURE.md +0 -0
  82. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/LICENSE.txt +0 -0
  83. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/Makefile +0 -0
  84. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/STREAMING.md +0 -0
  85. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/TYPES.md +0 -0
  86. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/artifact_udf/pyproject.toml +0 -0
  87. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/artifact_udf/src/example_udf/__init__.py +0 -0
  88. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/artifact_udf/src/example_udf/py.typed +0 -0
  89. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/artifact_udf/src/example_udf/tshirt_sizing.py +0 -0
  90. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/artifact_upload_example.py +0 -0
  91. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/byoidc_bearer_token_example.py +0 -0
  92. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/errors.py +0 -0
  93. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/interactive_oauth_login.py +0 -0
  94. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/simple_append_only_streaming_query_example.py +0 -0
  95. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/snapshot_mode_tuple_cursor_simple_example.py +0 -0
  96. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/examples/statement_properties_example.py +0 -0
  97. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/auth.py +0 -0
  98. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/changelog_compressor.py +0 -0
  99. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/execution_mode.py +0 -0
  100. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/oauth/config.py +0 -0
  101. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/oauth/http_json.py +0 -0
  102. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/oauth/pkce.py +0 -0
  103. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/oauth/provider.py +0 -0
  104. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/oauth/token_chain.py +0 -0
  105. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/oauth/token_set.py +0 -0
  106. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/statement.py +0 -0
  107. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/statement_properties.py +0 -0
  108. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/types.py +0 -0
  109. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/src/confluent_sql/variant.py +0 -0
  110. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/__init__.py +0 -0
  111. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_artifact.py +0 -0
  112. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/integration/test_fetch.py +0 -0
  113. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/oauth/test_callback_server_unit.py +0 -0
  114. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/oauth/test_config_unit.py +0 -0
  115. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/oauth/test_http_json_unit.py +0 -0
  116. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/oauth/test_pkce_unit.py +0 -0
  117. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/oauth/test_provider_unit.py +0 -0
  118. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/oauth/test_token_chain_unit.py +0 -0
  119. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/oauth/test_token_set_unit.py +0 -0
  120. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_auth_unit.py +0 -0
  121. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_changelog_compressor_unit.py +0 -0
  122. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_connection_credentials_unit.py +0 -0
  123. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_connectors_unit.py +0 -0
  124. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_execution_mode_unit.py +0 -0
  125. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_statement_properties_unit.py +0 -0
  126. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_statement_unit.py +0 -0
  127. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_tableflow_unit.py +0 -0
  128. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/tests/unit/test_types_unit.py +0 -0
  129. {confluent_sql-0.8.0 → confluent_sql-0.9.0}/uv.lock +0 -0
@@ -2,7 +2,35 @@
2
2
 
3
3
  All notable changes to this dbapi driver will be documented in this file.
4
4
 
5
- ## Unreleased
5
+ ## 0.9.0, 2026-11-16
6
+
7
+ ### Changed - Breaking
8
+
9
+ - The Tableflow methods moved off `Connection` into a new `TableflowApi` client (`confluent_sql.TableflowApi`), obtained from the new `Connection.get_tableflow_api()` like `get_artifacts_api()` and `get_connector_api()`. `Connection.enable_tableflow()`, `get_tableflow()`, `update_tableflow()` and `disable_tableflow()` are removed, with no deprecation shims: call `.enable()`, `.get()`, `.update()` and `.disable()` on the client instead, e.g. `connection.get_tableflow_api().enable("orders", table_formats=..., storage=...)`. Signatures, blocking behavior and exceptions are unchanged. (#289)
10
+ - Removed the `Connection` methods `connect_controlplane_request()`, `artifact_controlplane_request()`, `resolve_kafka_cluster_id()` and `artifact_scope()`. They were never documented as public: they only existed as hooks for the connector and artifact service APIs, which now receive a request callable, the environment id and (for connectors) a cluster-id resolver or (for artifacts) the cloud, region and endpoint at construction instead (`ConnectorApi`/`ArtifactsApi` are still obtained through `Connection`).
11
+ - Removed the undocumented `Connection.create_connector()`, `get_connector()`, `delete_connector()`, `pause_connector()` and `resume_connector()` passthroughs. Use `Connection.get_connector_api()`, the counterpart of `get_artifacts_api()`, and call `.create()`, `.get()`, `.delete()`, `.pause()` and `.resume()` on it. (#235) The `confluent_sql.service_api` module and the `ControlPlaneContext` and `ArtifactsContext` protocols are removed with them. (#235)
12
+ - `connect()` and `Connection.__init__()` no longer accept `http_timeout_secs`. The setting moved into the new frozen `Timeouts` dataclass (`confluent_sql.Timeouts`, defined in the new `confluent_sql.connect_options` module): replace `http_timeout_secs=5` with `timeouts=Timeouts(httpx_request_timeout_secs=5)`. `connect()` defaults `timeouts` to `DEFAULT_TIMEOUTS`; `Connection.__init__()` has no default and requires a `timeouts` keyword argument. Invalid values still raise `InterfaceError`, now naming the field (`Timeouts.httpx_request_timeout_secs must be positive, got 0`). `Connection.http_timeout_secs` remains as a read-only shorthand for `connection.timeouts.httpx_request_timeout_secs`. (#236)
13
+ - `confluent_sql.oauth.__all__` shrinks to the supported public surface: `OAuthMetrics` and `discard_login`, the function behind the documented `confluent_sql.oauth_discard_login()`, which is unchanged and remains the way to call it. (#313)
14
+
15
+ ### Added
16
+
17
+ - `cloud_provider` and `cloud_region` may now be omitted from `connect()` when the connection has control-plane reach (a global API key or `auth="oauth"`) and `database` (or `database_kafka_cluster_id`) is given. The lookup runs during `connect()`, so no match, several matches (`AmbiguousClusterError`, below) or a lookup failure surface there. Supplying only one of `cloud_provider` / `cloud_region` no longer raises when inference is possible: the other half is filled in from the cluster and the one supplied is checked against it (`ClusterMismatchError`, below), as is a `database` supplied beside a `database_kafka_cluster_id`; a complete provider+region pair is still trusted with no lookup. Private networking is not derivable, so private-link users keep passing `endpoint` (a cluster that looks private-only, attached to a network with no public access point, draws a warning to do so); BYOIDC and non-global API keys keep today's requirements, with the `InterfaceError` now naming the inference route as well. (#310)
18
+ - `ClusterMismatchError`, a subclass of `OperationalError` importable from `confluent_sql`, raised from `connect()` while cloud and region are being inferred when a supplied `database`, `cloud_provider` or `cloud_region` disagrees with the Kafka cluster the driver resolved. It carries the cluster as `.cluster_id` and every disagreement as `.mismatches` (`(parameter, supplied, actual)` triples; `.parameters` for just the names). Nothing is checked on paths that make no lookup (explicit `endpoint`, or a complete provider+region pair). (#310)
19
+ - `AmbiguousClusterError`, a subclass of `OperationalError` importable from `confluent_sql`, raised when several Kafka clusters in the environment share the connection's `database` name. It carries the candidates as `.clusters` (`(cluster_id, cloud, region)` triples; `.cluster_ids` for just the ids), so callers can catch it by type and pick one to pass as `database_kafka_cluster_id`. (#310)
20
+ - `AmbiguousOrganizationError`, a subclass of `OperationalError` importable from `confluent_sql`, raised when `organization_id` is omitted and the credential can reach more than one organization. It carries the candidates as `.organizations` (`(id, display_name)` pairs; `.organization_ids` for just the ids) and names them in its message, so callers can catch it by type instead of matching message text, and pick one to pass as `organization_id`. (#311)
21
+ - `ConnectorApi` and `TableflowApi` are now importable from `confluent_sql` (as `ArtifactsApi` already was), so callers can annotate what `get_connector_api()` and `get_tableflow_api()` return. (#289)
22
+ - `RequestTimeoutError`, a subclass of `OperationalError` importable from `confluent_sql`, raised when an individual HTTP request times out. Existing `except OperationalError` handlers keep working. (#236)
23
+
24
+ - `Timeouts.statement_results_response_wallclock_secs` (default 30.0), passed as `connect(..., timeouts=Timeouts(statement_results_response_wallclock_secs=...))`: the most wall-clock time a blocking result read spends getting one response to a fetch of statement results, however many timed-out attempts that takes. It is not a cap on a read's total duration. Override a single field with `dataclasses.replace(DEFAULT_TIMEOUTS, statement_results_response_wallclock_secs=60)`. A window no longer than `httpx_request_timeout_secs` leaves no room for a retry, so `Timeouts` emits a `UserWarning` for it. (#236)
25
+
26
+ ### Fixed
27
+
28
+ - `confluent_sql.paramstyle` now reads `"format"` (positional `%s` placeholders, which is what the driver has always accepted) instead of the incorrect `"pyformat"`. Code that branches on `paramstyle` (e.g. SQLAlchemy-style dialect detection) now sees the truth. (#223)
29
+ - Under `auth="oauth"`, an omitted `organization_id` is no longer taken silently from the login's default organization, which for a multi-organization user led to a confusing "environment not found" failure much later. The driver now lists the user's organizations (`GET /org/v2/organizations`) as part of the login, during `connect()`, applying the rule it already used for a global API key: exactly one is used, and more than one raises `AmbiguousOrganizationError`. That is a behavior change for multi-organization OAuth users who omitted `organization_id`: they now get the error from `connect()` and must pass `organization_id`. The login is refused along with the connection, so retrying with `organization_id` in the same process works (at the cost of a second browser login). A `connect()` that reuses an established login inherits its organization without listing again. A global key now behaves the same way: where an omitted `organization_id` used to be inferred lazily on first use of the connection, `connect()` now lists the organizations itself and raises `AmbiguousOrganizationError` (instead of a bare `OperationalError` from some later call) when several are reachable, so the failure moves from first use to `connect()` and costs one extra GET per `connect()` (message text changed; no organizations visible still raises `OperationalError`). (#311)
30
+ - Inside a timed wait (`Cursor.execute()`, the `wait_for_*` and `timeout=` calls) and a blocking result read's `statement_results_response_wallclock_secs` window, each HTTP request's timeouts are now capped at the time the wait has left, so a slow request can no longer overrun the wait's `timeout` by up to one `httpx_request_timeout_secs`. The cap applies to each of httpx's connect/read/write/pool timeouts separately, not to the request as a whole (httpx has no total-request deadline), so a server that trickles bytes can still run a little over. A retried GET also stops retrying once that deadline cannot outlast its next backoff, so neither a request nor a backoff sleep runs past it. (#236)
31
+ - A single slow status poll (an `httpx` connect/read/write/pool timeout, e.g. against a cold compute pool) no longer aborts `Cursor.execute()`'s readiness wait, `stop_statement(wait_for_stopped=True)`, the Tableflow `wait_for_running`/`wait_for_removal` waits, or the Connect (create/pause/resume/delete) and Artifacts (delete) waits. Such a poll is treated as "no news yet" and polled again until the call's own `timeout` expires. (#236)
32
+ - A single slow results-page fetch no longer aborts blocking reads of a statement's results (iterating a cursor, `fetchall()`, and snapshot-mode `fetchone()`/`fetchmany()`). The page is requested again, and `RequestTimeoutError` is raised only once timeouts have gone on for the connection's `Timeouts.statement_results_response_wallclock_secs` (default 30 seconds) of wall-clock time. Streaming-mode `fetchone()`/`fetchmany()` still make at most one request and raise `RequestTimeoutError` as before; the failed fetch leaves the cursor untouched, so calling again retries the same page. (#236)
33
+ - Idempotent GETs against the Connect, Tableflow, CMK and organization-lookup control-plane routes are now retried on transient transport errors (connection resets) and transient HTTP statuses (429/500/502/503/504), as Flink-gateway and Artifacts GETs already were. Mutating requests are still sent once. (#235)
6
34
 
7
35
  ## 0.8.0, 2026-10-30
8
36
 
@@ -0,0 +1,115 @@
1
+ # Repository conventions for Claude
2
+
3
+ Guidance for any Claude working in this repository. Keep it short and concrete; add a convention
4
+ here only once the codebase actually follows it in more than one place.
5
+
6
+ ## HTTP request routing: `ServiceClient`
7
+
8
+ Every HTTP request this driver makes goes through a `ServiceClient`
9
+ (`src/confluent_sql/service_client.py`), one per plane, held by `Connection`:
10
+
11
+ - `_dataplane` — the Flink gateway (statements and results).
12
+ - `_controlplane` — everything else: Tableflow, the CMK cluster lookup, the `/org/v2` organization
13
+ lookup, Connect, Artifacts. One client and pool, built without credentials. Each request names
14
+ the API it calls as a `ControlPlaneSurface` (`TABLEFLOW`, `CONNECT`, `ARTIFACTS`, `CMK`,
15
+ `ORGANIZATION`) through `Connection._controlplane_request(surface, url, ...)`, which attaches
16
+ that surface's credential (`_auth_for`, from `_surface_auth`) and applies its logging rule
17
+ (Artifacts never logs response bodies: the presign response carries a live upload URL). CMK and
18
+ organization lookups are global-key-only. A new surface is a new enum member, not a new client.
19
+
20
+ `ServiceClient.request(url, method="GET", raise_for_status=True, *, log_body=True, **kwargs)` is the
21
+ only way to send a request, and it decides retry from the method, so callers pick the plane (and,
22
+ on the control plane, the surface) they mean and never a retry policy:
23
+
24
+ - **GET is retried** via `call_with_retries()` (`src/confluent_sql/retry.py`) on transient transport
25
+ errors (`httpx.NetworkError`, `httpx.RemoteProtocolError`; #137) and transient HTTP statuses
26
+ (429/500/502/503/504, via `DEFAULT_RETRYABLE_STATUS_CODES`; #140), with a short exponential
27
+ backoff before giving up. Timeouts are deliberately not retried; wait loops tolerate them via
28
+ `poll_until` (#236), which also hands each attempt a Go-style `Context` (`context.py`) carrying
29
+ the wait's deadline; a blocking result read does the same with its
30
+ `statement_results_response_wallclock_secs` window. Pass it down explicitly as `ctx=` to the
31
+ request, and `ServiceClient.request` caps that request's httpx timeouts at the time left (per
32
+ phase: httpx has no total-request deadline), and a retried GET stops retrying once the deadline
33
+ cannot outlast the next backoff (`call_with_retries(..., ctx=)`). A new wait's attempt should
34
+ always forward its `ctx`. Timeouts are wall-clock budgets, never attempt counts. Status retries ride a private
35
+ `_RetryableStatusError` sentinel, so `call_with_retries` itself stays HTTP-agnostic.
36
+ - **Every other method is sent exactly once**: re-issuing a POST/PATCH/DELETE after a dropped
37
+ connection can double-submit or double-mutate state.
38
+
39
+ A caller that wants a specific status to become a specific exception passes
40
+ `status_exceptions={404: lambda response: SomeNotFoundError(...)}` (status -> factory that *returns*
41
+ the exception; the framework raises it) and an `error_prefix`, rather than `raise_for_status=False`
42
+ plus hand-written checks. Every other error status gets the standard `OperationalError` translation,
43
+ led by `error_prefix`. The mapping is consulted once the request is finished, so a factory mapped to
44
+ a retryable status fires only after a GET's retries are spent. `status_exceptions` / `error_prefix`
45
+ with `raise_for_status=False` is a contradiction and raises `ProgrammingError`; keep
46
+ `raise_for_status=False` only where the status is data (e.g. `delete_statement` treats 404 as
47
+ success) or the condition is not a plain status. Test fakes standing in for a `Requester` call
48
+ `apply_status_policy` so they exercise the real mapping.
49
+
50
+ Never reach for the raw `httpx.Client` (`ServiceClient.httpx_client`) to send a request; that
51
+ bypasses retries, error translation (every `httpx.RequestError` becomes `OperationalError`, #138;
52
+ timeouts become `RequestTimeoutError`) and the reauth policy. Don't add a family of request
53
+ methods on `Connection`: the plane's `ServiceClient` (or `_controlplane_request`) is the entry point.
54
+
55
+ The retry design was introduced in #137 (see `CHANGELOG.md` 0.4.1) after a reported `ECONNRESET`
56
+ while polling a single statement; #140 added status retries and #235 extended them from the Flink
57
+ gateway to every control-plane GET. The reasoning, and the case for a plain function over a
58
+ decorator, is captured in `retry.py`'s module docstring.
59
+
60
+ ## Blocking vs. non-blocking lifecycle methods
61
+
62
+ Methods that drive a server-side resource toward a steady state (start a statement, stop it,
63
+ enable/disable a Tableflow sink, etc.) follow a uniform shape:
64
+
65
+ - **Block by default; return the settled state.** The common call should leave the resource in its
66
+ intended terminal/ready state, not hand back a transient one the caller must then poll itself.
67
+ - **Expose a `wait_for_<settled-state>: bool = True` keyword-only argument.** The suffix names the
68
+ exact condition awaited — *not* a generic `wait`/`block`. Existing names: `wait_for_stopped`
69
+ (statement reaches STOPPED), `wait_for_running` (Tableflow topic reaches RUNNING),
70
+ `wait_for_removal` (Tableflow topic is gone). A new method picks the suffix that is literally
71
+ true of what it waits for.
72
+ - **Pair it with a uniform `timeout` keyword arg** (seconds; the standardized knob across all such
73
+ methods).
74
+ - **`=False` is the opt-out**: return as soon as the request is accepted (resource typically in a
75
+ PENDING/just-requested state).
76
+ - **While waiting, raise on terminal failure and on timeout** — surface the failure detail
77
+ (`OperationalError`, e.g. a statement/topic that went FAILED), don't silently return a broken
78
+ resource.
79
+ - **Implement the wait with `poll_until`** from `polling.py`: it owns the backoff, the deadline and
80
+ the `timeout` error, and treats one request timeout (`RequestTimeoutError`) as "no news yet"
81
+ rather than a failure (#236). Don't hand-roll a sleep loop, and don't call `sleep_with_backoff`
82
+ directly.
83
+
84
+ Exemplars: `Connection.stop_statement` / `Cursor.stop_statement` (`wait_for_stopped=True`),
85
+ `TableflowApi.enable` (`wait_for_running=True`), `TableflowApi.disable`
86
+ (`wait_for_removal=True`). The DDL convenience methods (`execute_snapshot_ddl`,
87
+ `execute_streaming_ddl`) block unconditionally and offer no opt-out — that's also acceptable when a
88
+ non-blocking variant would be meaningless.
89
+
90
+ ## The `oauth` test marker
91
+
92
+ Test modules exercising the interactive OAuth login -- everything under `tests/unit/oauth/`,
93
+ `test_connection_oauth_unit.py`, and the `tests/integration/test_oauth*.py` modules -- carry
94
+ `pytest.mark.oauth` via module-level `pytestmark`, alongside their `unit`/`integration` marker. A
95
+ new OAuth-only test module should prefer the same. A module that mixes OAuth and non-OAuth tests
96
+ (e.g. `tests/integration/test_infer_cloud.py`) may instead mark just its OAuth tests with
97
+ `@pytest.mark.oauth`, so the others aren't swept into `-m oauth` runs. It is a topic axis
98
+ orthogonal to unit/integration:
99
+
100
+ - `uv run pytest -m oauth` -- every OAuth test (integration ones skip without `RUN_OAUTH_TESTS`).
101
+ - `uv run pytest -m "oauth and unit"` -- the fast, browser-free subset.
102
+ - `RUN_OAUTH_TESTS=1 uv run pytest -n0 -m "oauth and integration"` -- the human-in-the-loop browser
103
+ run. `-n0` is mandatory: the loopback callback port is fixed, so parallel workers collide.
104
+
105
+ ## The `integration_with_mocks` test marker
106
+
107
+ Some integration tests are semi-real: they run against the live service, but wrap a real route or
108
+ client call to inject a fault (a dropped connection, a request timeout) or to augment the real
109
+ answer (a bogus extra organization or same-named cluster, so an ambiguity can be exercised on an
110
+ account that doesn't genuinely have one). Such a test carries just `pytest.mark.integration_with_mocks`;
111
+ the integration `conftest.py` adds `integration` automatically, so `-m integration` still selects it. The pattern:
112
+ capture the real function, call it for real, and only then tamper with what it returns (or fail
113
+ before delegating), so the real route and parsing still run and the test can't pass vacuously.
114
+ This pytest marker isn't so much for actually selecting and running this subset, but rather
115
+ to assist in finding similar technique tests (when being asked to write more)
@@ -600,7 +600,7 @@ cursor.delete_statement()
600
600
  ## Tableflow Lifecycle
601
601
 
602
602
  [Tableflow](https://www.confluent.io/product/tableflow/) materializes the Kafka topic backing a
603
- Flink table into an Iceberg or Delta table. Four `Connection` methods manage that sink. Enabling
603
+ Flink table into an Iceberg or Delta table. Four `TableflowApi` methods manage that sink; get the client with `Connection.get_tableflow_api()` (peer to `get_artifacts_api()` and `get_connector_api()`). Enabling
604
604
  it also unlocks
605
605
  [efficiency gains for snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html#snapshot-queries-and-tableflow)
606
606
  against the table.
@@ -617,16 +617,20 @@ A runnable example covering the full enable/get/disable lifecycle is in
617
617
  > authentication](README.md#byoidc-bearer-token-authentication)) fails closed on these methods —
618
618
  > use an API-key connection for Tableflow.
619
619
 
620
+ ```python
621
+ tableflow = connection.get_tableflow_api() # used by every example below
622
+ ```
623
+
620
624
  ### Selecting formats: `TableFormat`
621
625
 
622
626
  There is a single format vocabulary, `TableFormat` (`ICEBERG` / `DELTA`), on both the request and
623
627
  response sides. A topic can carry **both** formats at once (there is no per-format config), so
624
- `enable_tableflow`'s `table_formats` argument accepts either a single `TableFormat` for the
628
+ `TableflowApi.enable`'s `table_formats` argument accepts either a single `TableFormat` for the
625
629
  common case or a collection for both:
626
630
 
627
631
  ```python
628
- connection.enable_tableflow("orders", table_formats=TableFormat.ICEBERG, storage=...)
629
- connection.enable_tableflow(
632
+ tableflow.enable("orders", table_formats=TableFormat.ICEBERG, storage=...)
633
+ tableflow.enable(
630
634
  "orders", table_formats={TableFormat.ICEBERG, TableFormat.DELTA}, storage=...
631
635
  )
632
636
  ```
@@ -636,7 +640,7 @@ Responses name the same `TableFormat`s (`topic.spec.table_formats`,
636
640
  plain set comparison:
637
641
 
638
642
  ```python
639
- topic = connection.enable_tableflow(
643
+ topic = tableflow.enable(
640
644
  "orders", table_formats={TableFormat.ICEBERG, TableFormat.DELTA},
641
645
  storage=ManagedStorage(), wait_for_running=True,
642
646
  )
@@ -645,7 +649,7 @@ assert set(topic.spec.table_formats) == {TableFormat.ICEBERG, TableFormat.DELTA}
645
649
 
646
650
  ### Storage variants
647
651
 
648
- `enable_tableflow` requires an explicit, frozen storage spec — no silent default:
652
+ `TableflowApi.enable` requires an explicit, frozen storage spec — no silent default:
649
653
 
650
654
  - `ManagedStorage()` — Confluent-managed bucket, zero config.
651
655
  - `ByobAwsStorage(bucket_name=..., provider_integration_id=...)` — bring-your-own AWS S3 bucket.
@@ -664,12 +668,12 @@ The Tableflow API addresses the cluster by its `lkc-…` id, which the connectio
664
668
  that matches more than one cluster raises, listing the candidate ids so you can disambiguate with
665
669
  `database_kafka_cluster_id`.
666
670
 
667
- ### `enable_tableflow()` — add an Iceberg/Delta sink
671
+ ### `enable()` — add an Iceberg/Delta sink
668
672
 
669
673
  ```python
670
674
  from confluent_sql import ManagedStorage, TableFormat, TableflowPhase
671
675
 
672
- topic = connection.enable_tableflow(
676
+ topic = tableflow.enable(
673
677
  "orders",
674
678
  table_formats=TableFormat.ICEBERG,
675
679
  storage=ManagedStorage(),
@@ -689,23 +693,23 @@ assert topic.phase is TableflowPhase.RUNNING # blocked to RUNNING by default
689
693
  - Raises `TableflowTopicAlreadyExistsError` if Tableflow is already enabled (HTTP 409), or
690
694
  `ProgrammingError` if no management credential is available or the cluster id can't be resolved.
691
695
 
692
- ### `get_tableflow()` — read current state
696
+ ### `get()` — read current state
693
697
 
694
698
  ```python
695
- topic = connection.get_tableflow("orders")
699
+ topic = tableflow.get("orders")
696
700
  print(topic.phase) # TableflowPhase.PENDING / RUNNING / FAILED
697
701
  print(topic.spec.table_formats) # [TableFormat.ICEBERG, ...]
698
702
  ```
699
703
 
700
704
  Raises `TableflowTopicNotFoundError` if Tableflow is not enabled for the topic (HTTP 404). There is
701
- no separate health check — health is read off `get_tableflow(...).phase`.
705
+ no separate health check — health is read off `get(...).phase`.
702
706
 
703
- ### `update_tableflow()` — change formats/config on an existing sink
707
+ ### `update()` — change formats/config on an existing sink
704
708
 
705
709
  ```python
706
710
  from confluent_sql import TableflowTopicConfig, TableFormat, TableflowPhase
707
711
 
708
- topic = connection.update_tableflow(
712
+ topic = tableflow.update(
709
713
  "orders",
710
714
  table_formats={TableFormat.ICEBERG, TableFormat.DELTA},
711
715
  config=TableflowTopicConfig(retention_ms="1209600000"),
@@ -716,7 +720,7 @@ assert topic.phase is TableflowPhase.RUNNING # blocked to RUNNING by default
716
720
  Lets a caller change only `table_formats`/`config` on an already-enabled topic — a `PATCH`, not a
717
721
  disable/re-enable — so an in-place config change doesn't drop and rebuild the sink. `storage` and
718
722
  the table name itself are immutable server-side and have no in-place path; changing either requires
719
- `disable_tableflow` + `enable_tableflow` instead.
723
+ `disable` + `enable` instead.
720
724
 
721
725
  **Behavior notes:**
722
726
 
@@ -726,16 +730,16 @@ the table name itself are immutable server-side and have no in-place path; chang
726
730
  way: every `config` field has a server-enforced default and the server rejects an explicit null.
727
731
  - When `table_formats` is given, it replaces the full list rather than adding to it.
728
732
  - This method sends whatever it's given — it does not diff against the topic's current state.
729
- Compare against a prior `get_tableflow()` yourself if you only want to send what actually changed.
733
+ Compare against a prior `get()` yourself if you only want to send what actually changed.
730
734
  - Blocks until `RUNNING` by default (`wait_for_running=True`), raising `OperationalError` on
731
- `FAILED`, same as `enable_tableflow`. Pass `wait_for_running=False` to return as soon as the
735
+ `FAILED`, same as `enable`. Pass `wait_for_running=False` to return as soon as the
732
736
  update is accepted.
733
737
  - Raises `TableflowTopicNotFoundError` if Tableflow is not enabled for the topic (HTTP 404).
734
738
 
735
- ### `disable_tableflow()` — tear down the sink
739
+ ### `disable()` — tear down the sink
736
740
 
737
741
  ```python
738
- connection.disable_tableflow("orders") # blocks until confirmed gone by default
742
+ tableflow.disable("orders") # blocks until confirmed gone by default
739
743
  ```
740
744
 
741
745
  **Behavior notes:**
@@ -743,7 +747,7 @@ connection.disable_tableflow("orders") # blocks until confirmed gone by defaul
743
747
  - All-or-nothing in v1: removes the entire Tableflow topic. (Removing just one of two enabled
744
748
  formats needs a future API and is not yet supported.)
745
749
  - Deletion is asynchronous. Blocks until removal is confirmed by default (`wait_for_removal=True`),
746
- polling `get_tableflow` until it `404`s. This is why a following `DROP TABLE` is safe by default —
750
+ polling `get` until it `404`s. This is why a following `DROP TABLE` is safe by default —
747
751
  dropping the Flink table drops its backing topic, so Tableflow must be confirmed gone first to
748
752
  avoid racing an active materialization. Pass `wait_for_removal=False` to return as soon as the
749
753
  `DELETE` is accepted.
@@ -762,7 +766,7 @@ storage = ManagedStorage()
762
766
  config = TableflowTopicConfig(retention_ms="604800000")
763
767
 
764
768
  for table in ("orders", "shipments", "returns"):
765
- connection.enable_tableflow(
769
+ tableflow.enable(
766
770
  table,
767
771
  table_formats=TableFormat.ICEBERG,
768
772
  storage=storage,
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: confluent-sql
3
- Version: 0.8.0
3
+ Version: 0.9.0
4
4
  Summary: DB-API v2 compliant driver for Confluent Cloud Flink SQL
5
5
  Project-URL: Repository, https://github.com/confluentinc/confluent-sql
6
6
  Project-URL: Documentation, https://github.com/confluentinc/confluent-sql?tab=readme-ov-file#confluent-sql
@@ -259,7 +259,7 @@ The driver defaults to [snapshot mode](https://docs.confluent.io/cloud/current/f
259
259
  - a **BYOIDC bearer token** minted by your own OAuth/OIDC identity provider, passed as `external_access_token` / `identity_pool_id` (see [BYOIDC bearer-token authentication](#byoidc-bearer-token-authentication) below).
260
260
 
261
261
  The interactive browser login is the simplest way to get started, at the cost of one browser sign-in per process. A Global key works against every route this driver touches. A Flink Region key only works against the core Flink SQL routes (the main DB-API functionality), not other features such as Tableflow, Connectors, or Artifacts.
262
- - **Organization ID** — required with a Flink Region API key or a BYOIDC bearer token, neither of which can discover it. With a Global API key it may be omitted if the key can see exactly one organization, in which case it's inferred automatically on first use of the connection. With `auth="oauth"` it may always be omitted and defaults to your login's organization.
262
+ - **Organization ID** — required with a Flink Region API key or a BYOIDC bearer token, neither of which can discover it. With a Global API key or `auth="oauth"` it can usually be omitted: see [Inferred connection parameters](#inferred-connection-parameters).
263
263
 
264
264
  ### How to Obtain a Flink Region API Key
265
265
 
@@ -288,12 +288,13 @@ Instead of API keys, sign in once through your browser:
288
288
  conn = confluent_sql.connect(
289
289
  auth="oauth",
290
290
  environment_id="env-...",
291
- cloud_provider="aws",
292
- cloud_region="us-east-1",
291
+ database="my_cluster",
293
292
  )
294
293
  ```
295
294
 
296
- The browser opens once per process; the login is shared by every connection the process opens. `organization_id` is optional and defaults to your login's organization. See [examples/interactive_oauth_login.py](examples/interactive_oauth_login.py). The resulting login can reach everything your user account can, so all of the driver's functionality, including Tableflow, Connectors, and Artifacts, is available.
295
+ Only `environment_id` and `database` are needed: the organization, the cluster id, and the cloud provider and region are all inferred (see [Inferred connection parameters](#inferred-connection-parameters)).
296
+
297
+ The browser opens once per process; the login is shared by every connection the process opens. See [examples/interactive_oauth_login.py](examples/interactive_oauth_login.py). The resulting login can reach everything your user account can, so all of the driver's functionality, including Tableflow, Connectors, and Artifacts, is available.
297
298
 
298
299
  **Callback port.** To catch the browser's redirect after you sign in, the driver listens on `127.0.0.1:26642` (path `/callback-confluent-sql-docs`) while the login is in progress. This port is fixed by the driver's registered OAuth client and cannot be changed, so it must be free; if something else holds it, `connect()` raises `OAuthLoginError` with reason `PORT_IN_USE`. Only one login can be in progress per machine at a time. If you don't finish signing in within five minutes, it raises `OAuthLoginError` with reason `TIMED_OUT`.
299
300
 
@@ -333,10 +334,43 @@ The driver stamps `Authorization: Bearer <external_access_token>` and `Confluent
333
334
  Things to know:
334
335
 
335
336
  - **`external_access_token` and `identity_pool_id` are a pair** and are **mutually exclusive** with every API-key parameter (`global_*`, `flink_*`, `tableflow_*`, `connect_*`). Supplying a bearer token alongside any API key is rejected.
336
- - **Flink data plane only.** Confluent's authorization model does not accept a raw external token on any control-plane route this driver calls. So under BYOIDC the control-plane surfaces — Tableflow (`enable_tableflow` / `get_tableflow` / `disable_tableflow`), Connectors, and the CMK cluster-id lookup that resolves a `database` name to its `lkc-…` id — fail closed with a clear error. Use an API-key connection for those, and pass `database_kafka_cluster_id` to `connect()` if you need the driver to know the cluster id without the CMK lookup.
337
+ - **Flink data plane only.** Confluent's authorization model does not accept a raw external token on any control-plane route this driver calls. So under BYOIDC the control-plane surfaces — Tableflow (`TableflowApi`), Connectors, and the CMK cluster-id lookup that resolves a `database` name to its `lkc-…` id — fail closed with a clear error. Use an API-key connection for those, and pass `database_kafka_cluster_id` to `connect()` if you need the driver to know the cluster id without the CMK lookup.
337
338
  - **`organization_id` is required** under BYOIDC. Inferring it needs a control-plane call an external token can't make, so it must be supplied explicitly.
338
339
  - **No token refresh.** The token is used verbatim on every request. When it expires, requests begin failing (surfaced as `OperationalError`) and the connection is effectively dead — open a fresh connection with a fresh token.
339
340
 
341
+ ## Inferred connection parameters
342
+
343
+ With a credential that can reach the Confluent Cloud control plane -- a **Global API key** (`global_api_key` / `global_api_secret`) or **`auth="oauth"`** -- most of what `connect()` needs can be looked up for you. The only non-credential inputs required are `environment_id` and `database` (the database's display name):
344
+
345
+ ```python
346
+ # Interactive browser login
347
+ conn = confluent_sql.connect(auth="oauth", environment_id="env-...", database="my_cluster")
348
+
349
+ # Global API key
350
+ conn = confluent_sql.connect(
351
+ global_api_key="...", global_api_secret="...", environment_id="env-...", database="my_cluster"
352
+ )
353
+ ```
354
+
355
+ | Parameter | Inferred from | When |
356
+ |---|---|---|
357
+ | `organization_id` | The organizations the credential can reach (`GET /org/v2/organizations`; under OAuth, as part of the login) | During `connect()`. Exactly one is used; none raises `OperationalError`; several raise `AmbiguousOrganizationError` (its `.organizations` lists them), so pass `organization_id` to choose. |
358
+ | `cloud_provider`, `cloud_region` | The cloud and region of the Kafka cluster named by `database` (CMK cluster list) | During `connect()`, which then builds the public Flink endpoint from them. Either may be supplied and the other is filled in. Also used to scope Artifacts calls. |
359
+ | `database_kafka_cluster_id` | The `lkc-…` id of the cluster named by `database` (CMK cluster list) | During `connect()` when cloud and region are being inferred (the same single lookup serves both), otherwise on first use of Tableflow or Connectors. You normally never pass it; see below. |
360
+
361
+ Because inference happens during `connect()`, an unknown or ambiguous organization or database name fails there, not on the first statement.
362
+
363
+ **Precedence.** An explicit `endpoint` always wins, then an explicit `cloud_provider` *and* `cloud_region` pair, then inference, and anything you pass explicitly costs no extra requests. Supplying only one of `cloud_provider` / `cloud_region` makes the driver fill in the other from the cluster, and check the one you gave against it: a wrong one raises `ClusterMismatchError` (its `.mismatches` lists each parameter with what you supplied and what the cluster has), so a typo fails at `connect()`. A complete pair is trusted as given, with no lookup and no check.
364
+
365
+ **`database_kafka_cluster_id` is optional and rarely needed.** Pass it only to disambiguate, when several clusters share the `database` name (`AmbiguousClusterError`, whose `.clusters` lists the candidates), or to skip the lookup, e.g. to use Tableflow or Connectors with only their dedicated key pair. When you do pass it, the cluster is fetched directly by id, which is cheaper and means `database` is not needed to infer cloud and region. If you pass `database` too, it must match that cluster's name, or `ClusterMismatchError` is raised; that check only happens when the driver looks the cluster up anyway (the cloud/region inference above), never on paths that trust what you gave.
366
+
367
+ **What is never inferred.**
368
+
369
+ - `environment_id` is always required.
370
+ - `database` is required for cloud and region inference (an environment can span regions, so there is nothing else to go on); without it, pass `endpoint` or `cloud_provider` and `cloud_region`.
371
+ - **Private networking.** Inference only yields the public Flink endpoint. If your cluster needs private networking, pass `endpoint` (see [Private Networking Considerations](#private-networking-considerations)). When the cluster looks private-only (attached to a network, with no public access point), the driver logs a warning at `connect()` telling you so; it still connects with the public endpoint.
372
+ - **Flink Region API keys and BYOIDC** have no control-plane reach, so they keep their usual requirements: `organization_id`, plus `cloud_provider` and `cloud_region` (or `endpoint`).
373
+
340
374
  ## Installation
341
375
 
342
376
  ```bash
@@ -356,7 +390,7 @@ import confluent_sql
356
390
 
357
391
  # Connect to Confluent Cloud Flink SQL
358
392
  connection = confluent_sql.connect(
359
- organization_id="your-org-uuid", # optional if using a Global key -- see Prerequisites
393
+ organization_id="your-org-uuid", # optional with a Global key -- see "Inferred connection parameters"
360
394
  environment_id="env-123456",
361
395
  cloud_provider="aws",
362
396
  cloud_region="us-east-2",
@@ -466,7 +500,7 @@ For type support and examples, see **[TYPES.md](https://github.com/confluentinc/
466
500
 
467
501
  ## Private Networking Considerations
468
502
 
469
- By default, this driver uses the public Confluent Cloud API networking endpoint for the provided cloud provider and region. However, if the Flink database / Kafka cluster you intend to query requires private networking connectivity, then provide the appropriate Flink private networking base URL as the `endpoint` parameter
503
+ By default, this driver uses the public Confluent Cloud API networking endpoint for the provided (or [inferred](#inferred-connection-parameters)) cloud provider and region; inference only ever yields the public endpoint. However, if the Flink database / Kafka cluster you intend to query requires private networking connectivity, then provide the appropriate Flink private networking base URL as the `endpoint` parameter
470
504
  to `connect()` or `Connection.__init__()`. Refer to the Confluent Cloud [Flink private networking documentation](https://docs.confluent.io/cloud/current/flink/concepts/flink-private-networking.html) for more information on composing your endpoint URL.
471
505
 
472
506
  Symptoms of using the public endpoint when private networking is required include:
@@ -27,7 +27,7 @@ The driver defaults to [snapshot mode](https://docs.confluent.io/cloud/current/f
27
27
  - a **BYOIDC bearer token** minted by your own OAuth/OIDC identity provider, passed as `external_access_token` / `identity_pool_id` (see [BYOIDC bearer-token authentication](#byoidc-bearer-token-authentication) below).
28
28
 
29
29
  The interactive browser login is the simplest way to get started, at the cost of one browser sign-in per process. A Global key works against every route this driver touches. A Flink Region key only works against the core Flink SQL routes (the main DB-API functionality), not other features such as Tableflow, Connectors, or Artifacts.
30
- - **Organization ID** — required with a Flink Region API key or a BYOIDC bearer token, neither of which can discover it. With a Global API key it may be omitted if the key can see exactly one organization, in which case it's inferred automatically on first use of the connection. With `auth="oauth"` it may always be omitted and defaults to your login's organization.
30
+ - **Organization ID** — required with a Flink Region API key or a BYOIDC bearer token, neither of which can discover it. With a Global API key or `auth="oauth"` it can usually be omitted: see [Inferred connection parameters](#inferred-connection-parameters).
31
31
 
32
32
  ### How to Obtain a Flink Region API Key
33
33
 
@@ -56,12 +56,13 @@ Instead of API keys, sign in once through your browser:
56
56
  conn = confluent_sql.connect(
57
57
  auth="oauth",
58
58
  environment_id="env-...",
59
- cloud_provider="aws",
60
- cloud_region="us-east-1",
59
+ database="my_cluster",
61
60
  )
62
61
  ```
63
62
 
64
- The browser opens once per process; the login is shared by every connection the process opens. `organization_id` is optional and defaults to your login's organization. See [examples/interactive_oauth_login.py](examples/interactive_oauth_login.py). The resulting login can reach everything your user account can, so all of the driver's functionality, including Tableflow, Connectors, and Artifacts, is available.
63
+ Only `environment_id` and `database` are needed: the organization, the cluster id, and the cloud provider and region are all inferred (see [Inferred connection parameters](#inferred-connection-parameters)).
64
+
65
+ The browser opens once per process; the login is shared by every connection the process opens. See [examples/interactive_oauth_login.py](examples/interactive_oauth_login.py). The resulting login can reach everything your user account can, so all of the driver's functionality, including Tableflow, Connectors, and Artifacts, is available.
65
66
 
66
67
  **Callback port.** To catch the browser's redirect after you sign in, the driver listens on `127.0.0.1:26642` (path `/callback-confluent-sql-docs`) while the login is in progress. This port is fixed by the driver's registered OAuth client and cannot be changed, so it must be free; if something else holds it, `connect()` raises `OAuthLoginError` with reason `PORT_IN_USE`. Only one login can be in progress per machine at a time. If you don't finish signing in within five minutes, it raises `OAuthLoginError` with reason `TIMED_OUT`.
67
68
 
@@ -101,10 +102,43 @@ The driver stamps `Authorization: Bearer <external_access_token>` and `Confluent
101
102
  Things to know:
102
103
 
103
104
  - **`external_access_token` and `identity_pool_id` are a pair** and are **mutually exclusive** with every API-key parameter (`global_*`, `flink_*`, `tableflow_*`, `connect_*`). Supplying a bearer token alongside any API key is rejected.
104
- - **Flink data plane only.** Confluent's authorization model does not accept a raw external token on any control-plane route this driver calls. So under BYOIDC the control-plane surfaces — Tableflow (`enable_tableflow` / `get_tableflow` / `disable_tableflow`), Connectors, and the CMK cluster-id lookup that resolves a `database` name to its `lkc-…` id — fail closed with a clear error. Use an API-key connection for those, and pass `database_kafka_cluster_id` to `connect()` if you need the driver to know the cluster id without the CMK lookup.
105
+ - **Flink data plane only.** Confluent's authorization model does not accept a raw external token on any control-plane route this driver calls. So under BYOIDC the control-plane surfaces — Tableflow (`TableflowApi`), Connectors, and the CMK cluster-id lookup that resolves a `database` name to its `lkc-…` id — fail closed with a clear error. Use an API-key connection for those, and pass `database_kafka_cluster_id` to `connect()` if you need the driver to know the cluster id without the CMK lookup.
105
106
  - **`organization_id` is required** under BYOIDC. Inferring it needs a control-plane call an external token can't make, so it must be supplied explicitly.
106
107
  - **No token refresh.** The token is used verbatim on every request. When it expires, requests begin failing (surfaced as `OperationalError`) and the connection is effectively dead — open a fresh connection with a fresh token.
107
108
 
109
+ ## Inferred connection parameters
110
+
111
+ With a credential that can reach the Confluent Cloud control plane -- a **Global API key** (`global_api_key` / `global_api_secret`) or **`auth="oauth"`** -- most of what `connect()` needs can be looked up for you. The only non-credential inputs required are `environment_id` and `database` (the database's display name):
112
+
113
+ ```python
114
+ # Interactive browser login
115
+ conn = confluent_sql.connect(auth="oauth", environment_id="env-...", database="my_cluster")
116
+
117
+ # Global API key
118
+ conn = confluent_sql.connect(
119
+ global_api_key="...", global_api_secret="...", environment_id="env-...", database="my_cluster"
120
+ )
121
+ ```
122
+
123
+ | Parameter | Inferred from | When |
124
+ |---|---|---|
125
+ | `organization_id` | The organizations the credential can reach (`GET /org/v2/organizations`; under OAuth, as part of the login) | During `connect()`. Exactly one is used; none raises `OperationalError`; several raise `AmbiguousOrganizationError` (its `.organizations` lists them), so pass `organization_id` to choose. |
126
+ | `cloud_provider`, `cloud_region` | The cloud and region of the Kafka cluster named by `database` (CMK cluster list) | During `connect()`, which then builds the public Flink endpoint from them. Either may be supplied and the other is filled in. Also used to scope Artifacts calls. |
127
+ | `database_kafka_cluster_id` | The `lkc-…` id of the cluster named by `database` (CMK cluster list) | During `connect()` when cloud and region are being inferred (the same single lookup serves both), otherwise on first use of Tableflow or Connectors. You normally never pass it; see below. |
128
+
129
+ Because inference happens during `connect()`, an unknown or ambiguous organization or database name fails there, not on the first statement.
130
+
131
+ **Precedence.** An explicit `endpoint` always wins, then an explicit `cloud_provider` *and* `cloud_region` pair, then inference, and anything you pass explicitly costs no extra requests. Supplying only one of `cloud_provider` / `cloud_region` makes the driver fill in the other from the cluster, and check the one you gave against it: a wrong one raises `ClusterMismatchError` (its `.mismatches` lists each parameter with what you supplied and what the cluster has), so a typo fails at `connect()`. A complete pair is trusted as given, with no lookup and no check.
132
+
133
+ **`database_kafka_cluster_id` is optional and rarely needed.** Pass it only to disambiguate, when several clusters share the `database` name (`AmbiguousClusterError`, whose `.clusters` lists the candidates), or to skip the lookup, e.g. to use Tableflow or Connectors with only their dedicated key pair. When you do pass it, the cluster is fetched directly by id, which is cheaper and means `database` is not needed to infer cloud and region. If you pass `database` too, it must match that cluster's name, or `ClusterMismatchError` is raised; that check only happens when the driver looks the cluster up anyway (the cloud/region inference above), never on paths that trust what you gave.
134
+
135
+ **What is never inferred.**
136
+
137
+ - `environment_id` is always required.
138
+ - `database` is required for cloud and region inference (an environment can span regions, so there is nothing else to go on); without it, pass `endpoint` or `cloud_provider` and `cloud_region`.
139
+ - **Private networking.** Inference only yields the public Flink endpoint. If your cluster needs private networking, pass `endpoint` (see [Private Networking Considerations](#private-networking-considerations)). When the cluster looks private-only (attached to a network, with no public access point), the driver logs a warning at `connect()` telling you so; it still connects with the public endpoint.
140
+ - **Flink Region API keys and BYOIDC** have no control-plane reach, so they keep their usual requirements: `organization_id`, plus `cloud_provider` and `cloud_region` (or `endpoint`).
141
+
108
142
  ## Installation
109
143
 
110
144
  ```bash
@@ -124,7 +158,7 @@ import confluent_sql
124
158
 
125
159
  # Connect to Confluent Cloud Flink SQL
126
160
  connection = confluent_sql.connect(
127
- organization_id="your-org-uuid", # optional if using a Global key -- see Prerequisites
161
+ organization_id="your-org-uuid", # optional with a Global key -- see "Inferred connection parameters"
128
162
  environment_id="env-123456",
129
163
  cloud_provider="aws",
130
164
  cloud_region="us-east-2",
@@ -234,7 +268,7 @@ For type support and examples, see **[TYPES.md](https://github.com/confluentinc/
234
268
 
235
269
  ## Private Networking Considerations
236
270
 
237
- By default, this driver uses the public Confluent Cloud API networking endpoint for the provided cloud provider and region. However, if the Flink database / Kafka cluster you intend to query requires private networking connectivity, then provide the appropriate Flink private networking base URL as the `endpoint` parameter
271
+ By default, this driver uses the public Confluent Cloud API networking endpoint for the provided (or [inferred](#inferred-connection-parameters)) cloud provider and region; inference only ever yields the public endpoint. However, if the Flink database / Kafka cluster you intend to query requires private networking connectivity, then provide the appropriate Flink private networking base URL as the `endpoint` parameter
238
272
  to `connect()` or `Connection.__init__()`. Refer to the Confluent Cloud [Flink private networking documentation](https://docs.confluent.io/cloud/current/flink/concepts/flink-private-networking.html) for more information on composing your endpoint URL.
239
273
 
240
274
  Symptoms of using the public endpoint when private networking is required include:
@@ -1,7 +1,7 @@
1
1
  """Example of enabling and updating Tableflow on Google Cloud Storage (GCS).
2
2
 
3
3
  This mirrors ``tableflow_lifecycle_example.py`` but targets a customer-owned GCS bucket via the
4
- new ``GcsStorage`` backend, and additionally shows the ``update_tableflow`` in-place path and a
4
+ new ``GcsStorage`` backend, and additionally shows the ``TableflowApi.update`` in-place path and a
5
5
  non-blocking enable. Tableflow materializes the Kafka topic backing a Flink table into an
6
6
  Iceberg/Delta table; here the underlying files land in your own GCS bucket rather than a
7
7
  Confluent-managed one.
@@ -48,10 +48,12 @@ gcs = GcsStorage(
48
48
  provider_integration_id=os.environ["CONFLUENT_GCS_PROVIDER_INTEGRATION_ID"], # cspi-...
49
49
  )
50
50
 
51
+ tableflow = conn.get_tableflow_api()
52
+
51
53
  try:
52
54
  # Enable Iceberg on the GCS bucket, with a topic-level config. wait_for_running=True (the
53
55
  # default) blocks until the topic reaches RUNNING, raising OperationalError if it goes FAILED.
54
- topic = conn.enable_tableflow(
56
+ topic = tableflow.enable(
55
57
  table_name,
56
58
  table_formats=TableFormat.ICEBERG,
57
59
  storage=gcs,
@@ -71,7 +73,7 @@ try:
71
73
 
72
74
  # Add DELTA alongside the existing ICEBERG, in place -- no disable/re-enable cycle. Passing
73
75
  # only table_formats leaves config untouched; storage is immutable and has no update path.
74
- topic = conn.update_tableflow(
76
+ topic = tableflow.update(
75
77
  table_name,
76
78
  table_formats={TableFormat.ICEBERG, TableFormat.DELTA},
77
79
  )
@@ -79,20 +81,20 @@ try:
79
81
 
80
82
  # Bump retention without touching the format set. Each of config's own sub-fields is
81
83
  # independently "leave unchanged" when None, so this only rewrites retention_ms.
82
- conn.update_tableflow(
84
+ tableflow.update(
83
85
  table_name,
84
86
  config=TableflowTopicConfig(retention_ms=2_592_000_000), # 30 days
85
87
  )
86
88
 
87
89
  # A non-blocking enable would look like this (shown, not run, since it's already enabled):
88
- # conn.enable_tableflow(
90
+ # tableflow.enable(
89
91
  # other_table,
90
92
  # table_formats=TableFormat.ICEBERG,
91
93
  # storage=gcs,
92
94
  # wait_for_running=False, # returns immediately with the topic in PENDING
93
95
  # )
94
96
 
95
- conn.disable_tableflow(table_name)
97
+ tableflow.disable(table_name)
96
98
  print(f"disabled Tableflow on {table_name!r}")
97
99
  finally:
98
100
  conn.close()
@@ -27,10 +27,12 @@ conn = confluent_sql.connect(
27
27
  )
28
28
  table_name = os.getenv("CONFLUENT_TABLEFLOW_TABLE", "orders")
29
29
 
30
+ tableflow = conn.get_tableflow_api()
31
+
30
32
  try:
31
33
  # wait_for_running=True is the default: blocks until the topic reaches RUNNING, raising
32
34
  # OperationalError if it goes FAILED instead.
33
- topic = conn.enable_tableflow(
35
+ topic = tableflow.enable(
34
36
  table_name,
35
37
  table_formats=TableFormat.ICEBERG,
36
38
  storage=ManagedStorage(),
@@ -39,12 +41,12 @@ try:
39
41
  print(f"formats: {topic.spec.table_formats}")
40
42
  assert topic.phase is TableflowPhase.RUNNING
41
43
 
42
- topic = conn.get_tableflow(table_name)
44
+ topic = tableflow.get(table_name)
43
45
  print(f"current state: phase={topic.phase}, formats={topic.spec.table_formats}")
44
46
 
45
- # wait_for_removal=True is the default: blocks until get_tableflow(...) 404s, so a following
47
+ # wait_for_removal=True is the default: blocks until tableflow.get(...) 404s, so a following
46
48
  # DROP TABLE on the underlying topic is safe to issue right after this returns.
47
- conn.disable_tableflow(table_name)
49
+ tableflow.disable(table_name)
48
50
  print(f"disabled Tableflow on {table_name!r}")
49
51
  finally:
50
52
  conn.close()
@@ -91,6 +91,7 @@ testpaths = "tests"
91
91
  markers = [
92
92
  "unit: mark a test as a unit test",
93
93
  "integration: mark a test as an integration test",
94
+ "integration_with_mocks: mark an integration test that runs against the real service but wraps a real route or client call to inject a fault or augment its result (e.g. a dropped connection, a bogus extra cluster); implies `integration` automatically",
94
95
  "slow: mark a test as a slow (longer than a few seconds integration) test",
95
96
  "typeconv: mark a test as a type conversion test",
96
97
  "oauth: mark a test as exercising the interactive OAuth login (unit or integration)",
@@ -7,8 +7,6 @@ codeowners:
7
7
  enable: true
8
8
  renovatebot:
9
9
  enable: true
10
- automerge:
11
- enable: true
12
10
  semaphore:
13
11
  enable: true
14
12
  status_level: block
@@ -23,4 +21,7 @@ make:
23
21
  code_artifact:
24
22
  enable: true
25
23
  package_paths:
26
- - pypi-internal/pypi//confluent-sql*
24
+ - pypi-internal/pypi//confluent-sql*
25
+ automerge:
26
+ renovate:
27
+ enable: true