confluent-sql 0.7.0__tar.gz → 0.8.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 (109) hide show
  1. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/CHANGELOG.md +23 -0
  2. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/CLAUDE.md +12 -0
  3. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/PKG-INFO +49 -3
  4. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/README.md +48 -2
  5. confluent_sql-0.8.0/examples/interactive_oauth_login.py +43 -0
  6. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/pyproject.toml +10 -0
  7. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/__init__.py +12 -0
  8. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/__version__.py +1 -1
  9. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/artifacts.py +3 -12
  10. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/auth.py +4 -1
  11. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/connection.py +438 -135
  12. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/connectors.py +2 -6
  13. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/cursor.py +2 -2
  14. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/exceptions.py +109 -0
  15. confluent_sql-0.8.0/src/confluent_sql/oauth/__init__.py +56 -0
  16. confluent_sql-0.8.0/src/confluent_sql/oauth/callback_server.py +533 -0
  17. confluent_sql-0.8.0/src/confluent_sql/oauth/config.py +63 -0
  18. confluent_sql-0.8.0/src/confluent_sql/oauth/holder.py +398 -0
  19. confluent_sql-0.8.0/src/confluent_sql/oauth/http_json.py +108 -0
  20. confluent_sql-0.8.0/src/confluent_sql/oauth/pkce.py +38 -0
  21. confluent_sql-0.8.0/src/confluent_sql/oauth/provider.py +1015 -0
  22. confluent_sql-0.8.0/src/confluent_sql/oauth/token_chain.py +360 -0
  23. confluent_sql-0.8.0/src/confluent_sql/oauth/token_set.py +56 -0
  24. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/retry.py +3 -3
  25. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/statement.py +3 -6
  26. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/tableflow.py +2 -5
  27. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/utils.py +28 -0
  28. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/integration/conftest.py +38 -0
  29. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/integration/test_cursor.py +44 -17
  30. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/integration/test_fetch.py +9 -1
  31. confluent_sql-0.8.0/tests/integration/test_oauth.py +110 -0
  32. confluent_sql-0.8.0/tests/integration/test_oauth_rejected_org.py +48 -0
  33. confluent_sql-0.8.0/tests/integration/test_oauth_user_identity.py +79 -0
  34. confluent_sql-0.8.0/tests/integration/test_oauth_user_mismatch.py +91 -0
  35. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/conftest.py +16 -1
  36. confluent_sql-0.8.0/tests/unit/oauth/test_callback_server_unit.py +762 -0
  37. confluent_sql-0.8.0/tests/unit/oauth/test_config_unit.py +75 -0
  38. confluent_sql-0.8.0/tests/unit/oauth/test_holder_unit.py +809 -0
  39. confluent_sql-0.8.0/tests/unit/oauth/test_http_json_unit.py +133 -0
  40. confluent_sql-0.8.0/tests/unit/oauth/test_pkce_unit.py +42 -0
  41. confluent_sql-0.8.0/tests/unit/oauth/test_provider_unit.py +1728 -0
  42. confluent_sql-0.8.0/tests/unit/oauth/test_token_chain_unit.py +610 -0
  43. confluent_sql-0.8.0/tests/unit/oauth/test_token_set_unit.py +108 -0
  44. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_artifacts_connection_unit.py +1 -1
  45. confluent_sql-0.8.0/tests/unit/test_connection_oauth_unit.py +563 -0
  46. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_connection_unit.py +32 -4
  47. confluent_sql-0.8.0/tests/unit/test_package_unit.py +18 -0
  48. confluent_sql-0.8.0/tests/unit/test_utils_unit.py +35 -0
  49. confluent_sql-0.7.0/tests/unit/test_package_unit.py +0 -10
  50. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/.claude/rules/software-engineering.md +0 -0
  51. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/.github/CODEOWNERS +0 -0
  52. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/.gitignore +0 -0
  53. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/.semaphore/publish_to_pypi.yml +0 -0
  54. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/.semaphore/semaphore.yml +0 -0
  55. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/ARCHITECTURE.md +0 -0
  56. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/DBAPI_EXTENSIONS.md +0 -0
  57. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/LICENSE.txt +0 -0
  58. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/Makefile +0 -0
  59. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/STREAMING.md +0 -0
  60. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/TYPES.md +0 -0
  61. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/artifact_udf/pyproject.toml +0 -0
  62. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/artifact_udf/src/example_udf/__init__.py +0 -0
  63. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/artifact_udf/src/example_udf/py.typed +0 -0
  64. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/artifact_udf/src/example_udf/tshirt_sizing.py +0 -0
  65. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/artifact_upload_example.py +0 -0
  66. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/byoidc_bearer_token_example.py +0 -0
  67. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/errors.py +0 -0
  68. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/simple_append_only_streaming_query_example.py +0 -0
  69. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/snapshot_mode_tuple_cursor_simple_example.py +0 -0
  70. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/statement_properties_example.py +0 -0
  71. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/tableflow_gcs_example.py +0 -0
  72. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/examples/tableflow_lifecycle_example.py +0 -0
  73. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/service.yml +0 -0
  74. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/changelog_compressor.py +0 -0
  75. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/execution_mode.py +0 -0
  76. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/polling.py +0 -0
  77. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/result_readers.py +0 -0
  78. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/service_api.py +0 -0
  79. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/statement_properties.py +0 -0
  80. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/types.py +0 -0
  81. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/src/confluent_sql/variant.py +0 -0
  82. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/__init__.py +0 -0
  83. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/conftest.py +0 -0
  84. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/integration/test_artifact.py +0 -0
  85. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/integration/test_connection.py +0 -0
  86. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/integration/test_connector.py +0 -0
  87. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/integration/test_tableflow.py +0 -0
  88. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_artifacts_unit.py +0 -0
  89. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_auth_unit.py +0 -0
  90. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_changelog_compressor_unit.py +0 -0
  91. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_changelog_unit.py +0 -0
  92. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_connection_byoidc_unit.py +0 -0
  93. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_connection_close_unit.py +0 -0
  94. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_connection_connector_unit.py +0 -0
  95. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_connection_credentials_unit.py +0 -0
  96. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_connection_unit_properties.py +0 -0
  97. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_connectors_connection_unit.py +0 -0
  98. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_connectors_unit.py +0 -0
  99. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_cursor_unit.py +0 -0
  100. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_execution_mode_unit.py +0 -0
  101. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_polling_unit.py +0 -0
  102. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_result_readers_unit.py +0 -0
  103. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_retry_unit.py +0 -0
  104. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_statement_properties_unit.py +0 -0
  105. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_statement_unit.py +0 -0
  106. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_tableflow_connection_unit.py +0 -0
  107. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_tableflow_unit.py +0 -0
  108. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/tests/unit/test_types_unit.py +0 -0
  109. {confluent_sql-0.7.0 → confluent_sql-0.8.0}/uv.lock +0 -0
@@ -2,6 +2,29 @@
2
2
 
3
3
  All notable changes to this dbapi driver will be documented in this file.
4
4
 
5
+ ## Unreleased
6
+
7
+ ## 0.8.0, 2026-10-30
8
+
9
+ ### Changed - Breaking
10
+
11
+ - `Connection.__init__`'s positional parameters are reordered: `organization_id` now comes after `cloud_provider`/`cloud_region`/`endpoint` (previously it was second, right after `environment_id`).
12
+
13
+ ### Added
14
+
15
+ - Interactive browser login: `connect(auth="oauth", ...)` signs in once through your browser instead of requiring API keys, and the login is shared by every connection in the process. `organization_id` is optional. While the login is in progress the driver listens on the fixed loopback port `127.0.0.1:26642`, which must be free (otherwise `OAuthLoginError` with reason `PORT_IN_USE`). See the README and `examples/interactive_oauth_login.py` (#150).
16
+ - `confluent_sql.oauth_discard_login()`: discard the process's shared interactive OAuth login. Closing a `Connection` never does this; the next `connect(auth="oauth", ...)` opens the browser again. (#150)
17
+ - `connect(..., reauth="auto"|"raise")` (with `auth="oauth"` only): what to do once an OAuth session can no longer be refreshed. `"auto"` (default) opens the browser for a fresh login and retries the request; `"raise"` raises `ReauthenticationRequired` instead, for unattended runs. (#150)
18
+ - New exceptions, all subclasses of `OperationalError` and importable from `confluent_sql` (#150):
19
+ - `OAuthLoginError`: the interactive browser login could not complete. Its `reason` is an `OAuthLoginFailure`: `TIMED_OUT`, `PORT_IN_USE`, `AUTHORIZATION_DENIED`, `SERVER_ERROR`, or (on re-authentication) `USER_MISMATCH`.
20
+ - `OAuthTokenEndpointError`: the auth service's token endpoint rejected a request. Carries the OAuth `error_code` (e.g. `"invalid_grant"`) and `http_status_code`.
21
+ - `ReauthenticationRequired`: the session can only be recovered by a fresh login. Its `reason` is a `ReauthenticationReason`: `ABSOLUTE_EXPIRY` (the ~8h session limit) or `REFRESH_REJECTED`.
22
+
23
+ ### Changed
24
+
25
+ - `organization_id` is now genuinely optional on both `connect()` and `Connection()` when it can be self-discovered (configured to use either oauth or a global API key).
26
+ - Direct `Connection()` construction's `organization_id` requirement (introduced in 0.6.0, #213) does not apply under `auth="oauth"`, which discovers the organization from the interactive login's session.
27
+
5
28
  ## 0.7.0, 2026-10-19
6
29
 
7
30
  ### Added
@@ -58,3 +58,15 @@ Exemplars: `Connection.stop_statement` / `Cursor.stop_statement` (`wait_for_stop
58
58
  (`wait_for_removal=True`). The DDL convenience methods (`execute_snapshot_ddl`,
59
59
  `execute_streaming_ddl`) block unconditionally and offer no opt-out — that's also acceptable when a
60
60
  non-blocking variant would be meaningless.
61
+
62
+ ## The `oauth` test marker
63
+
64
+ Every test module exercising the interactive OAuth login -- everything under `tests/unit/oauth/`,
65
+ `test_connection_oauth_unit.py`, and the `tests/integration/test_oauth*.py` modules -- carries
66
+ `pytest.mark.oauth` via module-level `pytestmark`, alongside its `unit`/`integration` marker. A new
67
+ OAuth test module must do the same. It is a topic axis orthogonal to unit/integration:
68
+
69
+ - `uv run pytest -m oauth` -- every OAuth test (integration ones skip without `RUN_OAUTH_TESTS`).
70
+ - `uv run pytest -m "oauth and unit"` -- the fast, browser-free subset.
71
+ - `RUN_OAUTH_TESTS=1 uv run pytest -n0 -m "oauth and integration"` -- the human-in-the-loop browser
72
+ run. `-n0` is mandatory: the loopback callback port is fixed, so parallel workers collide.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: confluent-sql
3
- Version: 0.7.0
3
+ Version: 0.8.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
@@ -253,12 +253,13 @@ The driver defaults to [snapshot mode](https://docs.confluent.io/cloud/current/f
253
253
  - **Confluent Cloud account** with Flink environment
254
254
  - **Existing Flink Database** (Confluent Cloud Kafka cluster)
255
255
  - **API credentials**, one of:
256
+ - an **interactive browser login**, with `auth="oauth"` (see [Interactive login](#interactive-browser-login) below), or
256
257
  - a **"Global" Confluent Cloud API key** and secret, passed as `global_api_key` / `global_api_secret`, or
257
258
  - a **Flink Region API key** and secret, passed as `flink_api_key` / `flink_api_secret`, or
258
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).
259
260
 
260
- A Global key works against every route this driver touches, so it is the more future-proof choice; a Flink Region key works against the Flink SQL routes that are the driver's focus today. Provide at least one pair. If you supply both, the Global pair is used and the Flink pair is ignored. A half-supplied pair (a key without its secret, or vice versa) is rejected.
261
- - **Organization ID** — required, *unless* you're using a Global API key and it can see exactly one organization, in which case you can omit `organization_id` and it's inferred automatically on first use of the connection. A Flink Region key has no way to discover it, so it always requires `organization_id` explicitly.
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
263
 
263
264
  ### How to Obtain a Flink Region API Key
264
265
 
@@ -279,6 +280,34 @@ To create or find a Flink Region API key:
279
280
 
280
281
  API keys may also be generated using the Confluent CLI or by API access, outside the scope of this document.
281
282
 
283
+ ### Interactive browser login
284
+
285
+ Instead of API keys, sign in once through your browser:
286
+
287
+ ```python
288
+ conn = confluent_sql.connect(
289
+ auth="oauth",
290
+ environment_id="env-...",
291
+ cloud_provider="aws",
292
+ cloud_region="us-east-1",
293
+ )
294
+ ```
295
+
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.
297
+
298
+ **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
+ **Login lifetime and signing out.** The login is held for the life of the process: closing a `Connection` does not sign you out, and a later `connect(auth="oauth", ...)` in the same process reuses it without another browser bounce. To explicitly discard the login (and its tokens), for example in a long-lived notebook kernel or server, call `confluent_sql.oauth_discard_login()`. The next `connect(auth="oauth", ...)` will then open the browser again. `oauth_discard_login()` closes the shared login's HTTP client immediately, so it must only be called once nothing is using the login: stop any OAuth activity and close every OAuth `Connection` first. A connection left open will fail at its next token refresh (including one triggered by a 401), and a refresh already in progress can be interrupted, even if the refresh token is still valid.
301
+
302
+ **Session lifetime and re-authentication.** A login's refresh token has a hard ~8 hour absolute lifetime (and expires sooner if idle for too long or revoked), after which the session can no longer be silently refreshed. What happens next is controlled by the `reauth` argument to `connect()`:
303
+
304
+ - `reauth="auto"` (the default): the driver opens the browser for a fresh sign-in and retries the failed request. Every connection in the process shares the new login. This suits interactive use such as notebooks and scripts run by a person.
305
+ - `reauth="raise"`: the request raises `confluent_sql.ReauthenticationRequired` instead. Use this for unattended runs (a long batch job or dbt run started and left running), where nobody would be at the browser. Its `reason` is `ABSOLUTE_EXPIRY` (the ~8 hour wall) or `REFRESH_REJECTED` (idle expiry or revocation); catch it to abort or restart the job cleanly.
306
+
307
+ Re-authentication must be completed as the same user who originally signed in. If a different user signs in, even within the same organization, the driver raises `OAuthLoginError` with reason `OAuthLoginFailure.USER_MISMATCH` and the session stays unauthenticated, so you can sign in again as the original user.
308
+
309
+ This check relies on the user identity claims in the login's token, and is strict: a re-authentication whose token carries no identity comparable to the original's is refused the same way, as is one that names a user when the original login's token named none. The only case let through unchecked is a login whose token never named a user at all, where the driver logs a warning at login and has nothing to compare.
310
+
282
311
  ### BYOIDC bearer-token authentication
283
312
 
284
313
  If your Confluent Cloud organization is configured with your own registered OAuth/OIDC identity provider, you can authenticate to the **Flink data plane** with a bearer token you mint yourself (an "external" token in Confluent's authorization vocabulary) rather than a Confluent API key. Pass the token and the identity-pool id that scopes it:
@@ -488,3 +517,20 @@ Run tests:
488
517
  ```bash
489
518
  uv run pytest
490
519
  ```
520
+
521
+ #### OAuth tests
522
+
523
+ Every OAuth test (unit and integration) carries the `oauth` pytest marker. The OAuth *integration* tests open your browser for a real Confluent Cloud sign-in, so they are opt-in: they skip unless `RUN_OAUTH_TESTS` is set (they also need `CONFLUENT_ENV_ID`, `CONFLUENT_CLOUD_PROVIDER` and `CONFLUENT_CLOUD_REGION`; some need `CONFLUENT_TEST_DBNAME`). A plain `uv run pytest` therefore runs the OAuth unit tests only.
524
+
525
+ ```bash
526
+ # Fast, browser-free OAuth unit tests only
527
+ uv run pytest -m "oauth and unit"
528
+
529
+ # The browser-driven OAuth integration tests only
530
+ RUN_OAUTH_TESTS=1 uv run pytest -n0 -m "oauth and integration"
531
+
532
+ # Every OAuth test, unit and integration
533
+ RUN_OAUTH_TESTS=1 uv run pytest -n0 -m oauth tests
534
+ ```
535
+
536
+ `-n0` is required for any run that includes the integration tests: the loopback callback port is fixed, so parallel workers would collide (and open several browsers at once).
@@ -21,12 +21,13 @@ The driver defaults to [snapshot mode](https://docs.confluent.io/cloud/current/f
21
21
  - **Confluent Cloud account** with Flink environment
22
22
  - **Existing Flink Database** (Confluent Cloud Kafka cluster)
23
23
  - **API credentials**, one of:
24
+ - an **interactive browser login**, with `auth="oauth"` (see [Interactive login](#interactive-browser-login) below), or
24
25
  - a **"Global" Confluent Cloud API key** and secret, passed as `global_api_key` / `global_api_secret`, or
25
26
  - a **Flink Region API key** and secret, passed as `flink_api_key` / `flink_api_secret`, or
26
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).
27
28
 
28
- A Global key works against every route this driver touches, so it is the more future-proof choice; a Flink Region key works against the Flink SQL routes that are the driver's focus today. Provide at least one pair. If you supply both, the Global pair is used and the Flink pair is ignored. A half-supplied pair (a key without its secret, or vice versa) is rejected.
29
- - **Organization ID** — required, *unless* you're using a Global API key and it can see exactly one organization, in which case you can omit `organization_id` and it's inferred automatically on first use of the connection. A Flink Region key has no way to discover it, so it always requires `organization_id` explicitly.
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
31
 
31
32
  ### How to Obtain a Flink Region API Key
32
33
 
@@ -47,6 +48,34 @@ To create or find a Flink Region API key:
47
48
 
48
49
  API keys may also be generated using the Confluent CLI or by API access, outside the scope of this document.
49
50
 
51
+ ### Interactive browser login
52
+
53
+ Instead of API keys, sign in once through your browser:
54
+
55
+ ```python
56
+ conn = confluent_sql.connect(
57
+ auth="oauth",
58
+ environment_id="env-...",
59
+ cloud_provider="aws",
60
+ cloud_region="us-east-1",
61
+ )
62
+ ```
63
+
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.
65
+
66
+ **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
+ **Login lifetime and signing out.** The login is held for the life of the process: closing a `Connection` does not sign you out, and a later `connect(auth="oauth", ...)` in the same process reuses it without another browser bounce. To explicitly discard the login (and its tokens), for example in a long-lived notebook kernel or server, call `confluent_sql.oauth_discard_login()`. The next `connect(auth="oauth", ...)` will then open the browser again. `oauth_discard_login()` closes the shared login's HTTP client immediately, so it must only be called once nothing is using the login: stop any OAuth activity and close every OAuth `Connection` first. A connection left open will fail at its next token refresh (including one triggered by a 401), and a refresh already in progress can be interrupted, even if the refresh token is still valid.
69
+
70
+ **Session lifetime and re-authentication.** A login's refresh token has a hard ~8 hour absolute lifetime (and expires sooner if idle for too long or revoked), after which the session can no longer be silently refreshed. What happens next is controlled by the `reauth` argument to `connect()`:
71
+
72
+ - `reauth="auto"` (the default): the driver opens the browser for a fresh sign-in and retries the failed request. Every connection in the process shares the new login. This suits interactive use such as notebooks and scripts run by a person.
73
+ - `reauth="raise"`: the request raises `confluent_sql.ReauthenticationRequired` instead. Use this for unattended runs (a long batch job or dbt run started and left running), where nobody would be at the browser. Its `reason` is `ABSOLUTE_EXPIRY` (the ~8 hour wall) or `REFRESH_REJECTED` (idle expiry or revocation); catch it to abort or restart the job cleanly.
74
+
75
+ Re-authentication must be completed as the same user who originally signed in. If a different user signs in, even within the same organization, the driver raises `OAuthLoginError` with reason `OAuthLoginFailure.USER_MISMATCH` and the session stays unauthenticated, so you can sign in again as the original user.
76
+
77
+ This check relies on the user identity claims in the login's token, and is strict: a re-authentication whose token carries no identity comparable to the original's is refused the same way, as is one that names a user when the original login's token named none. The only case let through unchecked is a login whose token never named a user at all, where the driver logs a warning at login and has nothing to compare.
78
+
50
79
  ### BYOIDC bearer-token authentication
51
80
 
52
81
  If your Confluent Cloud organization is configured with your own registered OAuth/OIDC identity provider, you can authenticate to the **Flink data plane** with a bearer token you mint yourself (an "external" token in Confluent's authorization vocabulary) rather than a Confluent API key. Pass the token and the identity-pool id that scopes it:
@@ -256,3 +285,20 @@ Run tests:
256
285
  ```bash
257
286
  uv run pytest
258
287
  ```
288
+
289
+ #### OAuth tests
290
+
291
+ Every OAuth test (unit and integration) carries the `oauth` pytest marker. The OAuth *integration* tests open your browser for a real Confluent Cloud sign-in, so they are opt-in: they skip unless `RUN_OAUTH_TESTS` is set (they also need `CONFLUENT_ENV_ID`, `CONFLUENT_CLOUD_PROVIDER` and `CONFLUENT_CLOUD_REGION`; some need `CONFLUENT_TEST_DBNAME`). A plain `uv run pytest` therefore runs the OAuth unit tests only.
292
+
293
+ ```bash
294
+ # Fast, browser-free OAuth unit tests only
295
+ uv run pytest -m "oauth and unit"
296
+
297
+ # The browser-driven OAuth integration tests only
298
+ RUN_OAUTH_TESTS=1 uv run pytest -n0 -m "oauth and integration"
299
+
300
+ # Every OAuth test, unit and integration
301
+ RUN_OAUTH_TESTS=1 uv run pytest -n0 -m oauth tests
302
+ ```
303
+
304
+ `-n0` is required for any run that includes the integration tests: the loopback callback port is fixed, so parallel workers would collide (and open several browsers at once).
@@ -0,0 +1,43 @@
1
+ """Example of interactive human-login OAuth: sign in once via a browser instead of
2
+ supplying API keys.
3
+
4
+ Running this pops a browser to Confluent Cloud for a one-time interactive sign-in (the driver
5
+ listens on 127.0.0.1:26642 for the redirect); once you consent, the resulting login is reused for
6
+ every Connection this process opens -- one browser bounce per process, even under something like
7
+ dbt's multi-threaded mode.
8
+
9
+ organization_id is optional under auth="oauth": omitted, it's discovered from your login session
10
+ (your default Confluent Cloud organization); supplied, it scopes the login to that organization
11
+ instead.
12
+
13
+ To sign in against a non-production Confluent Cloud environment instead, import `STAG` or `DEVEL`
14
+ (`from confluent_sql.oauth.config import STAG`) and pass `oauth_config=STAG` to
15
+ `confluent_sql.connect()`. Note that `oauth_config` only redirects the *login*: resource endpoints
16
+ still default to production. You must also pass the matching non-production Flink gateway as
17
+ `endpoint=` (https://flink.<region>.<cloud>.<environment>.cpdev.cloud, where <environment> is
18
+ `stag` or `devel`) and, for control-plane operations (Tableflow, Connectors, Artifacts), the
19
+ matching `controlplane_endpoint=` (https://api.<environment>.cpdev.cloud). Otherwise the example's
20
+ statements go to the production gateway with non-production credentials. Cloud provider and
21
+ region are not needed when `endpoint=` is given.
22
+ """
23
+
24
+ import os
25
+
26
+ import confluent_sql
27
+
28
+ conn = confluent_sql.connect(
29
+ auth="oauth",
30
+ environment_id=os.environ["CONFLUENT_ENV_ID"],
31
+ cloud_provider=os.environ["CONFLUENT_CLOUD_PROVIDER"],
32
+ cloud_region=os.environ["CONFLUENT_CLOUD_REGION"],
33
+ )
34
+ print(f"Signed in to Confluent Cloud for organization {conn.organization_id!r}")
35
+
36
+ cursor = conn.cursor()
37
+ try:
38
+ cursor.execute("SELECT 1 as test_value_1, 2 as test_value_2, 3 as test_value_3")
39
+ for row in cursor:
40
+ print(f"iterating over cursor results: {row}")
41
+ finally:
42
+ cursor.close()
43
+ conn.close()
@@ -67,6 +67,15 @@ verboseOutput = true
67
67
  pythonVersion = "3.10"
68
68
  pythonPlatform = "All"
69
69
  include = ["src", "tests", "examples"]
70
+ # Default to requiring fully parameter type annotation (src/, examples/)
71
+ reportMissingParameterType = "error"
72
+ executionEnvironments = [
73
+ # But let tests/ not require parameter type annotations (at this time).
74
+ # (extraPaths is needed because an environment's root is also its import root: without it,
75
+ # tests' `from tests.conftest import ...` (needs ".") and `import confluent_sql` (needs "src")
76
+ # stop resolving.)
77
+ { root = "tests", reportMissingParameterType = "none", extraPaths = [".", "src"] }
78
+ ]
70
79
 
71
80
  [tool.pytest.ini_options]
72
81
  addopts = [
@@ -84,6 +93,7 @@ markers = [
84
93
  "integration: mark a test as an integration test",
85
94
  "slow: mark a test as a slow (longer than a few seconds integration) test",
86
95
  "typeconv: mark a test as a type conversion test",
96
+ "oauth: mark a test as exercising the interactive OAuth login (unit or integration)",
87
97
  ]
88
98
 
89
99
  [project.optional-dependencies]
@@ -37,8 +37,13 @@ from .exceptions import (
37
37
  InterfaceError,
38
38
  InternalError,
39
39
  NotSupportedError,
40
+ OAuthLoginError,
41
+ OAuthLoginFailure,
42
+ OAuthTokenEndpointError,
40
43
  OperationalError,
41
44
  ProgrammingError,
45
+ ReauthenticationReason,
46
+ ReauthenticationRequired,
42
47
  StatementDeletedError,
43
48
  StatementNotFoundError,
44
49
  StatementStoppedError,
@@ -48,6 +53,7 @@ from .exceptions import (
48
53
  Warning,
49
54
  )
50
55
  from .execution_mode import ExecutionMode
56
+ from .oauth import discard_login as oauth_discard_login
51
57
  from .result_readers import ChangeloggedRow
52
58
  from .statement import HIDDEN_LABEL, Op, StatementWarning, WarningSeverity
53
59
  from .statement_properties import (
@@ -119,6 +125,12 @@ __all__ = [
119
125
  "UploadRetry",
120
126
  "ConnectorNotFoundError",
121
127
  "ConnectorAlreadyExistsError",
128
+ "OAuthLoginError",
129
+ "OAuthLoginFailure",
130
+ "OAuthTokenEndpointError",
131
+ "ReauthenticationReason",
132
+ "ReauthenticationRequired",
133
+ "oauth_discard_login",
122
134
  "Connector",
123
135
  "ConnectorSpec",
124
136
  "ConnectorStatus",
@@ -1,3 +1,3 @@
1
1
  """Version information for the confluent_sql package."""
2
2
 
3
- __version__ = "0.7.0"
3
+ __version__ = "0.8.0"
@@ -13,7 +13,6 @@ from __future__ import annotations
13
13
  import os
14
14
  import time
15
15
  from dataclasses import dataclass, field
16
- from enum import Enum
17
16
  from pathlib import PurePath
18
17
  from typing import NamedTuple, Protocol, Union
19
18
  from urllib.parse import quote
@@ -30,7 +29,7 @@ from .polling import sleep_with_backoff
30
29
  from .retry import call_with_retries
31
30
  from .service_api import ServiceApi
32
31
  from .types import StrAnyDict
33
- from .utils import extract_error_detail, next_page_token
32
+ from .utils import ExtensibleEnum, extract_error_detail, next_page_token
34
33
 
35
34
  ArtifactFile = Union[str, "os.PathLike[str]"]
36
35
  """Path of the archive to upload."""
@@ -122,15 +121,7 @@ class Fields:
122
121
  PAGE_TOKEN = "page_token"
123
122
 
124
123
 
125
- class _ExtensibleEnum(str, Enum):
126
- """Extensible API enum: an unrecognized value parses to `UNKNOWN` instead of raising."""
127
-
128
- @classmethod
129
- def _missing_(cls, value: object):
130
- return cls.__members__["UNKNOWN"]
131
-
132
-
133
- class ArtifactContentFormat(_ExtensibleEnum):
124
+ class ArtifactContentFormat(ExtensibleEnum):
134
125
  """Archive format of an artifact: a JAR for Java UDFs, a ZIP for Python ones."""
135
126
 
136
127
  JAR = "JAR"
@@ -138,7 +129,7 @@ class ArtifactContentFormat(_ExtensibleEnum):
138
129
  UNKNOWN = "UNKNOWN"
139
130
 
140
131
 
141
- class ArtifactRuntimeLanguage(_ExtensibleEnum):
132
+ class ArtifactRuntimeLanguage(ExtensibleEnum):
142
133
  """Language runtime an artifact's code targets."""
143
134
 
144
135
  JAVA = "JAVA"
@@ -1,7 +1,10 @@
1
1
  """Custom httpx authentication schemes for Confluent SQL connections.
2
2
 
3
3
  Today this holds BYOIDC bearer-token auth for the Flink data plane (#100). The interactive-login
4
- OAuth effort will add its own httpx.Auth adapters alongside FlinkBearerAuth here.
4
+ OAuth effort's two adapters deliberately live elsewhere -- in `oauth/provider.py`, next to the
5
+ `CCloudOAuth` whose lock-guarded token slot and refresh gate they reach into. A `FlinkBearerAuth`
6
+ is self-contained (it holds its own token and never refreshes); those are views onto a shared,
7
+ mutating provider, and splitting them from it would buy nothing but an import cycle.
5
8
  """
6
9
 
7
10
  from __future__ import annotations